VALARM
email actions.
.env.example | ||
.gitignore | ||
LICENSE | ||
README.md |
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 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.