110 lines
2.7 KiB
Markdown
110 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Copy the example config and fill in your credentials:
|
|
|
|
```bash
|
|
cp config.example.yaml config.yaml
|
|
```
|
|
|
|
```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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo cp imap-idle-caldav.service /etc/systemd/system/
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now imap-idle-caldav
|
|
```
|
|
|
|
Check status and logs:
|
|
|
|
```bash
|
|
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
|