109 lines
No EOL
2.8 KiB
Markdown
109 lines
No EOL
2.8 KiB
Markdown
# 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:
|
|
|
|
```env
|
|
...
|
|
```
|
|
|
|
## Building the Docker Image
|
|
|
|
```bash
|
|
docker build -t caldav-reminder .
|
|
```
|
|
|
|
## Running the Container
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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. |