# 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:

```bash
.env.example
```

To get started:

1. Copy the file:
```bash
cp .env.example .env
```
    
2. Edit `.env` and fill in your CalDAV, SMTP, and scheduling details
    
3. 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

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

[AGPL v3.0 or later](LICENSE)