wagesj45/caldav-email-reminders
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions
a lightweight, self-hosted service that polls a CalDAV calendar and sends email reminders for upcoming events with VALARM email actions.
10 commits 1 branch 0 tags 54 KiB
Find a file
Exact
wagesj45 8bc512d9ae Not needed. 
This is a vestigial file from when the two scripts were going to be run by a `cron` job.
2025-05-05 03:37:07 -05:00
.env.example Update .env.example 2025-05-01 17:20:47 -05:00
.gitignore Initial commit 2025-05-01 15:28:36 -05:00
dispatch.py Initial Code Commit 2025-05-01 17:04:01 -05:00
Dockerfile Initial Code Commit 2025-05-01 17:04:01 -05:00
entrypoint.sh Initial Code Commit 2025-05-01 17:04:01 -05:00
LICENSE Initial commit 2025-05-01 15:28:36 -05:00
README.md Update README.md 2025-05-01 18:05:17 -05:00
sync.py Initial Code Commit 2025-05-01 17:04:01 -05:00

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 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 Configuration

All configuration is done via environment variables. An example file is provided:

.env.example

To get started:

  1. Copy the file:
cp .env.example .env

  1. Edit .env and fill in your CalDAV, SMTP, and scheduling details

  2. 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.

License

AGPL v3.0 or later