ics_mailimporter/README.md

ICS-Importer für mailbox.org unter Linux

Dieses Projekt durchsucht ein mailbox.org-Postfach per IMAP nach E-Mails mit .ics-Anhängen und importiert enthaltene Termine automatisch per CalDAV in einen mailbox.org-Kalender.[cite:55][cite:45]

Überblick

Der technische Ablauf ist bewusst einfach gehalten:

1. Das Python-Skript verbindet sich per IMAP mit mailbox.org und durchsucht einen Ordner, standardmäßig INBOX.[cite:56][cite:55]
2. Es erkennt .ics-Anhänge, berechnet einen Hash als Duplikat-Schutz und verarbeitet nur neue Anhänge.
3. Die Termine werden per CalDAV in den gewünschten mailbox.org-Kalender geschrieben, dessen URL in mailbox.org über die Kalendereigenschaften ermittelt wird.[cite:45][cite:51]
4. Die Ausführung erfolgt manuell oder stündlich per Cron.

Voraussetzungen

Benötigt werden:

• Linux
• Python 3
• pipenv
• Ein mailbox.org-Konto
• Zugriff auf IMAP und CalDAV
• Bei aktiver Zwei-Faktor-Authentifizierung ein App- bzw. Applikationspasswort für externe Anwendungen.[cite:63][cite:45]

Projektstruktur

ics-importer/
├── ics_mail_importer_env.py
├── .env.example
├── .env
├── imported_uids.txt
├── ics_importer.log
├── cron.log
└── README.md

Installation

Projektverzeichnis anlegen und Abhängigkeiten installieren:

mkdir -p ~/ics-importer
cd ~/ics-importer
pipenv install python-dotenv caldav icalendar

python-dotenv liest Schlüssel-Wert-Paare aus einer .env-Datei und stellt sie als Umgebungsvariablen bereit.[cite:162][cite:164]

Konfiguration mit .env

Eine .env.example kann als Vorlage verwendet werden:

IMAP_HOST=imap.mailbox.org
IMAP_PORT=993
IMAP_USERNAME=ihr-name@mailbox.org
IMAP_PASSWORD=IHR_PASSWORT_ODER_APP_PASSWORT
IMAP_FOLDER=INBOX
IMAP_UNSEEN_ONLY=true
IMAP_MARK_AS_READ=false

CALDAV_URL=https://dav.mailbox.org/caldav/IHR_KALENDER_ID
CALDAV_USERNAME=ihr-name@mailbox.org
CALDAV_PASSWORD=IHR_PASSWORT_ODER_APP_PASSWORT

Die IMAP-Standardwerte für mailbox.org sind imap.mailbox.org, Port 993, SSL/TLS und die vollständige E-Mail-Adresse als Benutzername.[cite:56][cite:55]

Die vollständige CalDAV-URL des Zielkalenders wird in mailbox.org im Kalender über Eigenschaften angezeigt; für Thunderbird und andere Clients wird https://dav.mailbox.org/caldav/XXX verwendet, wobei XXX die individuelle Kalender-ID ist.[cite:45][cite:51]

.env lokal anlegen und schützen:

cp .env.example .env
chmod 600 .env
nano .env

Bedeutung der Variablen

Variable	Bedeutung
IMAP_HOST	mailbox.org IMAP-Server, normalerweise imap.mailbox.org.[cite:56]
IMAP_PORT	IMAP-SSL-Port, normalerweise 993.[cite:56]
IMAP_USERNAME	mailbox.org-E-Mail-Adresse.[cite:55]
IMAP_PASSWORD	Passwort oder E-Mail-App-Passwort bei aktiver 2FA.[cite:63]
IMAP_FOLDER	Zu durchsuchender Ordner, meist INBOX.
IMAP_UNSEEN_ONLY	Wenn true, werden nur ungelesene Mails geprüft.
IMAP_MARK_AS_READ	Wenn true, werden verarbeitete Mails als gelesen markiert.
CALDAV_URL	Vollständige CalDAV-URL des Zielkalenders.[cite:45]
CALDAV_USERNAME	mailbox.org-E-Mail-Adresse als CalDAV-Benutzername.[cite:45]
CALDAV_PASSWORD	Passwort oder Applikationspasswort bei aktiver 2FA.[cite:63][cite:45]

Python-Skript

Das Skript ics_mail_importer_env.py nutzt python-dotenv, imaplib, email, icalendar und caldav. python-dotenv ist speziell dafür gedacht, Werte aus einer .env-Datei zu laden und als Umgebungsvariablen verfügbar zu machen.[cite:162][cite:164]

Beispielhafter Programmstart:

cd ~/ics-importer
pipenv run python3 ics_mail_importer_env.py

Das Skript erzeugt oder nutzt dabei unter anderem diese Dateien:

• ics_importer.log für die Programmausgabe
• imported_uids.txt für den Duplikat-Schutz
• optional cron.log, wenn die Cron-Ausgabe dorthin umgeleitet wird

Erster Testlauf

Vor dem Cron-Einsatz sollte das Skript immer einmal manuell gestartet werden:

pipenv run python3 ics_mail_importer_env.py

Wenn die Zugangsdaten korrekt sind, verbindet sich das Skript mit IMAP, liest passende Anhänge und importiert neue Termine in den angegebenen CalDAV-Kalender.[cite:55][cite:45]

Cron-Einrichtung

Den Python-Pfad des Pipenv-Umfelds ermitteln:

cd ~/ics-importer
pipenv --py

Stündlicher Cron-Eintrag:

0 * * * * /home/hans/.local/share/virtualenvs/ics-importer-wOz4rK-o/bin/python /home/hans/ics-importer/ics_mail_importer_env.py >> /home/hans/ics-importer/cron.log 2>&1

Die User-Crontab wird mit crontab -e gepflegt; die direkte Bearbeitung der Crontab-Dateien ist nicht empfehlenswert. Für stündliche Jobs sind sowohl 0 * * * * als auch @hourly übliche Varianten.[cite:321][cite:55]

Logrotation

Wenn cron.log mitgeschrieben wird, sollte die Datei per logrotate rotiert werden. Eine typische Konfiguration unter /etc/logrotate.d/ics-importer sieht so aus:

/home/hans/ics-importer/cron.log {
    weekly
    rotate 4
    compress
    delaycompress
    missingok
    notifempty
    create 0644 hans hans
}

Damit wird das Log wöchentlich rotiert, vier Versionen bleiben erhalten und ältere Logs werden komprimiert.

mailbox.org in Thunderbird

Für das eigentliche Projekt ist Thunderbird nicht zwingend nötig, aber mailbox.org empfiehlt für E-Mail in Thunderbird IMAP und für Kalender CalDAV.[cite:55][cite:45]

IMAP in Thunderbird

Thunderbird erkennt mailbox.org in der Regel automatisch; empfohlen wird IMAP statt POP3.[cite:55][cite:63]

CalDAV in Thunderbird

Kalender lassen sich in Thunderbird über Datei → Neu → Kalender → Im Netzwerk → CalDAV einbinden. Als URL dient die vollständige mailbox.org-CalDAV-Adresse des Kalenders.[cite:45][cite:51]

In manchen Setups muss in Thunderbird zusätzlich calendar.network.multirealm auf true gesetzt werden, damit die Authentifizierung sauber funktioniert.[cite:45][cite:51]

Sicherheit

.env enthält Zugangsdaten im Klartext und darf nicht in ein öffentliches Repository eingecheckt werden. python-dotenv ist für lokale Konfigurationsdateien gedacht, ersetzt aber kein Secret-Management-System.[cite:162][cite:164]

Empfehlungen:

• .env nur lokal speichern
• chmod 600 .env setzen
• .env in .gitignore eintragen
• Bei aktiver 2FA App-/Applikationspasswörter statt des Hauptpassworts verwenden.[cite:63][cite:45]

Fehlersuche

IMAP funktioniert nicht

Prüfen:

• IMAP_HOST=imap.mailbox.org
• IMAP_PORT=993
• vollständige E-Mail-Adresse als Benutzername
• korrektes Passwort oder App-Passwort bei aktiver 2FA.[cite:56][cite:63]

CalDAV funktioniert nicht

Prüfen:

• vollständige CalDAV-URL aus den Kalendereigenschaften in mailbox.org
• korrekter Benutzername
• korrektes Passwort bzw. Applikationspasswort bei aktiver 2FA.[cite:45][cite:51]

Cron führt das Skript nicht aus

Prüfen:

• absoluter Python-Pfad aus pipenv --py
• absoluter Skriptpfad
• Schreibrechte für cron.log
• manueller Testlauf funktioniert bereits

Empfohlener Betriebsmodus

Für die meisten Setups ist IMAP_UNSEEN_ONLY=true sinnvoll, damit nur neue bzw. ungelesene Mails geprüft werden. In Verbindung mit dem Hash-basierten Duplikat-Schutz verhindert das unnötige Doppelimporte und reduziert die Last auf dem Postfach.