CalDAV Email Reminder Service

This project provides a self-contained, Dockerized email reminder system that polls a CalDAV calendar, extracts scheduled email alarms (VALARM with ACTION:EMAIL), and delivers reminder emails based on their defined trigger times. It is designed as a workaround for CalDAV servers that either do not support email reminders or are unreliable in doing so.

Features

• Pulls events from one or more CalDAV calendars using standard REPORT queries

• Expands recurring events using RRULE and supports date-only and timezone-aware events

• Identifies and schedules VALARM blocks with ACTION:EMAIL

• Sends email reminders using SMTP with support for SSL or STARTTLS

• Uses a lightweight SQLite database for state tracking and deduplication

• Configurable via .env and runs entirely within Docker

• Emits all logs to Docker stdout (docker logs) — no syslog or cron daemon needed

• Handles long-term sync and dispatch via simple background loops

How It Works

1. sync.py:

   • Discovers calendar URLs (or uses those provided).

   • Downloads .ics files for all VEVENTs.

   • Extracts VALARM blocks with ACTION:EMAIL.

   • Calculates trigger times based on TRIGGER + DTSTART.

   • Stores scheduled reminders in SQLite.

2. dispatch.py:

   • Runs periodically to find due reminders.

   • Sends emails via SMTP.

   • Marks each reminder as sent to prevent duplicates.

3. entrypoint.sh:

   • Exports environment variables.

   • Starts two background loops:

     • Syncs calendar events every SYNC_INTERVAL seconds.

     • Dispatches reminders every DISPATCH_INTERVAL seconds.

Requirements

• Docker

• A CalDAV server with accessible credentials

• SMTP credentials for an outbound mail service

Environment Variables

Place these in a .env file in the root of your project:

...

Building the Docker Image

docker build -t caldav-reminder .

Running the Container

docker run -d --rm \
--env-file .env \
-v caldav_reminder_db:/data \
--name caldav-cron \
caldav-reminder

All output is logged to stdout and can be viewed with:

docker logs -f caldav-cron

Notes

• The database stores event UIDs, last-modified timestamps, and reminder entries to avoid duplicate processing.

• Recurring events are expanded into individual trigger times within a sliding window.

• Email reminders are only sent for future occurrences not yet marked as sent.

• This project assumes a single recipient address (EMAIL_TO) for simplicity.

License

[MIT License] or other appropriate license of your choosing.