imap-idle-caldav

A Python daemon that monitors an IMAP mailbox via IDLE for iMIP emails (event invitations, RSVP replies, cancellations) and ICS attachments, then updates a CalDAV calendar accordingly.

Features

IMAP IDLE — real-time monitoring with automatic reconnection and exponential backoff
iMIP support — handles REQUEST (create/update), REPLY (attendee RSVP), and CANCEL methods
ICS attachments — picks up .ics files and application/ics MIME parts
CalDAV sync — creates, updates, and cancels events on any CalDAV server (Nextcloud, Radicale, etc.)
Graceful shutdown — handles SIGTERM/SIGINT cleanly

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Copy the example config and fill in your credentials:

cp config.example.yaml config.yaml

imap:
  host: imap.example.com
  port: 993
  username: user@example.com
  password: secret
  folder: INBOX
  ssl: true

caldav:
  url: https://caldav.example.com/dav/calendars/user/calendar/
  username: user@example.com
  password: secret

logging:
  level: INFO   # DEBUG, INFO, WARNING, ERROR

Usage

# Using the entry point
imap-idle-caldav -c config.yaml

# Or as a module
python -m imap_idle_caldav -c config.yaml

The daemon will connect to IMAP, enter IDLE mode, and process incoming calendar emails as they arrive. It re-idles every 5 minutes per RFC 2177 and automatically reconnects on disconnection.

Systemd Service

Create a service user and install the app:

sudo useradd -r -s /usr/sbin/nologin imap-idle-caldav
sudo mkdir -p /opt/imap-idle-caldav
sudo python3 -m venv /opt/imap-idle-caldav/.venv
sudo /opt/imap-idle-caldav/.venv/bin/pip install .

Put your config in place:

sudo mkdir -p /etc/imap-idle-caldav
sudo cp config.yaml /etc/imap-idle-caldav/config.yaml
sudo chmod 600 /etc/imap-idle-caldav/config.yaml
sudo chown imap-idle-caldav: /etc/imap-idle-caldav/config.yaml

Install and start the service:

sudo cp imap-idle-caldav.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now imap-idle-caldav

Check status and logs:

sudo systemctl status imap-idle-caldav
sudo journalctl -u imap-idle-caldav -f

Edit the ExecStart path and User in the unit file if your install location or user differs.

Project Structure

imap_idle_caldav/
├── __main__.py          # Entry point, signal handling
├── config.py            # YAML config loading & validation
├── imap_client.py       # IMAP connection & IDLE loop
├── email_processor.py   # ICS extraction from emails
└── caldav_client.py     # CalDAV create/update/cancel operations

License

MIT

2.7 KiB Raw Permalink Blame History