Files

Dan Head c87a99f570 Add IMAP to Nextcloud Calendar importer

- IMAP mailbox monitoring with SSL/TLS, STARTTLS and plain connection support
- ICS attachment extraction from emails and import to Nextcloud via CalDAV
- Create or update calendar events by UID to avoid duplicates
- Event filtering by summary (contains, regex or exact match, with inversion)
- Deduplication by regex pattern extracted from event summaries
- Move or mark processed emails as seen after import
- Continuous polling mode and one-time run mode
- Fully configurable via environment variables
- Docker and Docker Compose support
- Test suite with pytest

2026-04-03 09:47:45 +01:00

2.4 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

IMAP to Nextcloud Calendar Importer - A Python utility that monitors an IMAP mailbox for emails with ICS calendar attachments and imports them to a Nextcloud calendar via CalDAV.

Commands

Build and Run

# Build Docker image
docker build -t imap-calendar-importer .

# Run with Docker Compose (continuous mode)
docker-compose up -d

# Run once and exit
docker-compose run --rm imap-calendar-importer

# View logs
docker-compose logs -f

# Rebuild after code changes
docker-compose up -d --build

Direct Python Execution

# Install dependencies
pip install -r requirements.txt

# Run directly (requires .env or environment variables set)
python imap_calendar_importer.py

Testing

# Create virtual environment and install dependencies
python -m venv .venv
.venv/bin/pip install -r requirements.txt

# Run all tests
.venv/bin/pytest tests/ -v

# Run specific test class
.venv/bin/pytest tests/test_imap_calendar_importer.py::TestMatchesFilter -v

# Run with coverage (requires pytest-cov)
.venv/bin/pytest tests/ --cov=imap_calendar_importer --cov-report=term-missing

Architecture

Single-file Python application (imap_calendar_importer.py) with one main class:

IMAPCalendarImporter - Handles the complete workflow:

connect_imap() - Establishes IMAP connection (SSL/TLS, STARTTLS, or plain)
connect_caldav() - Connects to Nextcloud CalDAV and discovers target calendar
process_emails() - Searches for unseen emails, extracts ICS attachments
extract_ics_attachments() - Parses MIME messages, applies summary filtering
import_ics_to_calendar() - Creates new or updates existing events by UID

Execution Modes:

Continuous: Polls mailbox every CHECK_INTERVAL seconds
One-time: Processes once and exits (RUN_ONCE=true)

Configuration

All configuration via environment variables (see .env.sample). Key settings:

IMAP_* - Mail server connection (server, port, credentials, SSL options)
CALDAV_* - Nextcloud connection (URL, credentials, calendar name)
SUMMARY_FILTER* - Event filtering by title (contains/regex/exact, with inversion)
RUN_ONCE / CHECK_INTERVAL - Execution mode control

Dependencies

caldav - CalDAV client library
icalendar - ICS parsing
urllib3 - HTTP client (used by caldav)

2.4 KiB Raw Blame History