VALARM
email actions.
.env.example | ||
.gitignore | ||
caldav-cron | ||
dispatch.py | ||
Dockerfile | ||
entrypoint.sh | ||
LICENSE | ||
README.md | ||
sync.py |
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 withACTION: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
-
sync.py:
-
Discovers calendar URLs (or uses those provided).
-
Downloads
.ics
files for all VEVENTs. -
Extracts
VALARM
blocks withACTION:EMAIL
. -
Calculates trigger times based on
TRIGGER
+DTSTART
. -
Stores scheduled reminders in SQLite.
-
-
dispatch.py:
-
Runs periodically to find due reminders.
-
Sends emails via SMTP.
-
Marks each reminder as sent to prevent duplicates.
-
-
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 Configuration
All configuration is done via environment variables. An example file is provided:
.env.example
To get started:
- Copy the file:
cp .env.example .env
-
Edit
.env
and fill in your CalDAV, SMTP, and scheduling details -
Run the container using that
.env
file
The app supports custom sync and dispatch intervals, authentication for CalDAV and SMTP, and full control over how reminders are sent. See .env.example
for all available options and default values.
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.