ics_mailimporter/README.md

README: ICS-Importer für mailbox.org unter Linux

Dieses Projekt durchsucht ein mailbox.org-Postfach per IMAP nach .ics-Anhängen und importiert enthaltene Termine anschließend per CalDAV in einen mailbox.org-Kalender. mailbox.org dokumentiert Thunderbird/IMAP für E-Mail und CalDAV für Kalender; die CalDAV-URL des Zielkalenders wird in mailbox.org im Kalender über Eigenschaften angezeigt. kb.mailbox

Voraussetzungen

Benötigt werden ein Linux-System, Python 3, pipenv, ein mailbox.org-Konto sowie Zugangsdaten für IMAP und CalDAV. Wenn bei mailbox.org die Zwei-Faktor-Authentifizierung aktiv ist, sollen für externe Anwendungen App-Passwörter beziehungsweise Applikationspasswörter verwendet werden. kb.mailbox

Projektinhalt

Die typische Struktur des Projekts sieht so aus:

ics-importer/
├── ics_mail_importer.py
├── config.ini.example
├── config.ini
├── imported_uids.txt
├── ics_importer.log
└── cron.log

ics_mail_importer.py ist das Hauptskript, config.ini enthält die Zugangsdaten, imported_uids.txt dient als Duplikat-Schutz, und cron.log kann die Ausgabe des Cron-Jobs aufnehmen. Der Duplikat-Schutz ist sinnvoll, weil bei wiederkehrender IMAP-Prüfung sonst identische ICS-Anhänge mehrfach verarbeitet würden. github

Installation mit pipenv

In das Projektverzeichnis wechseln und die Python-Abhängigkeiten installieren:

cd ~/ics-importer
pipenv install caldav icalendar

caldav wird für den Zugriff auf den CalDAV-Kalender benötigt, während icalendar ICS-Dateien parst; für das Mail-Lesen werden Standardbibliotheken wie imaplib und email verwendet. github

Den Interpreter-Pfad des Pipenv-Umfelds kann man mit folgendem Befehl prüfen:

cd ~/ics-importer
pipenv --py

Pipenv dokumentiert virtuelle Umgebungen und deren Interpreter-Pfade explizit; dieser Pfad ist später für Cron praktisch. pipenv.pypa

Konfiguration

Die Vorlage kopieren und bearbeiten:

cp config.ini.example config.ini
nano config.ini

Beispielinhalt:

[imap]
host         = imap.mailbox.org
port         = 993
username     = ihr-name@mailbox.org
password     = IHR_PASSWORT_ODER_APP_PASSWORT
folder       = INBOX
unseen_only  = true
mark_as_read = false

[caldav]
url          = https://dav.mailbox.org/caldav/IHR_KALENDER_ID
username     = ihr-name@mailbox.org
password     = IHR_PASSWORT_ODER_APP_PASSWORT

Die IMAP-Einstellungen orientieren sich an mailbox.org für Thunderbird, und die CalDAV-URL des gewünschten Kalenders wird laut mailbox.org im Kalenderbereich über die Eigenschaften des Kalenders ermittelt. kb.mailbox

Bedeutung der wichtigsten Optionen

Schlüssel	Bedeutung
imap.host	IMAP-Server von mailbox.org: imap.mailbox.org. kb.mailbox
imap.port	Standardport für IMAP über SSL: 993. kb.mailbox
imap.folder	Zu prüfender Ordner, meist INBOX.
imap.unseen_only	Wenn true, werden nur ungelesene Nachrichten gesucht; das reduziert unnötige Prüfungen.
imap.mark_as_read	Wenn true, markiert das Skript verarbeitete Nachrichten als gelesen.
caldav.url	Vollständige CalDAV-URL des Zielkalenders aus mailbox.org. kb.mailbox
caldav.username	Meist die mailbox.org-E-Mail-Adresse. kb.mailbox
caldav.password	Passwort oder App-/Applikationspasswort bei aktiver 2FA. kb.mailbox

Erster Testlauf

Das Skript kann manuell getestet werden mit:

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

Dabei werden neue .ics-Anhänge gesucht, importiert und im Log protokolliert. Python-Lösungen für IMAP-Anhangsextraktion und ICS-zu-CalDAV-Import folgen genau diesem Muster aus Mail-Abruf, Parsing und Import. stackoverflow

Stündliche Ausführung mit Cron

Die eigene User-Crontab wird mit crontab -e bearbeitet; User-Crontabs liegen auf Debian-/Raspberry-Pi-ähnlichen Systemen typischerweise unter /var/spool/cron/crontabs/, sollen aber nicht direkt bearbeitet werden. cronitor

Für eine Ausführung stündlich zur vollen Stunde sieht der Eintrag so aus:

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

Alternativ ist auch @hourly möglich; beide Varianten entsprechen einer stündlichen Ausführung, wobei die klassische Cron-Syntax mit 0 * * * * die Ausführung zur Minute 0 jeder Stunde beschreibt. wiki.ubuntuusers

Cron-Eintrag ohne eigenes Umleitungslog

Wenn die zusätzliche Datei cron.log nicht gewünscht ist, kann die Umleitung weggelassen werden:

0 * * * * /home/hans/.local/share/virtualenvs/ics-importer-wOz4rK-o/bin/python /home/hans/ics-importer/ics_mail_importer.py

Logrotation für cron.log

Für benutzerdefinierte Logs ist logrotate der übliche Weg unter Linux. Eine eigene Datei unter /etc/logrotate.d/ ist dafür die gängige Methode. dash0

Beispiel:

sudo nano /etc/logrotate.d/ics-importer

Inhalt:

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

Diese Konfiguration rotiert wöchentlich, behält vier alte Versionen, komprimiert alte Logs und legt nach der Rotation eine neue Datei mit passenden Rechten an. putorius

Zum Testen der Konfiguration:

sudo logrotate -d /etc/logrotate.d/ics-importer
sudo logrotate -f /etc/logrotate.d/ics-importer

Einfügen in vim-nox

Wenn crontab -e mit Vim geöffnet wird, kann im Insert-Modus oft direkt mit Strg+Shift+V aus dem Terminal-Zwischenspeicher eingefügt werden. Wenn Vim mit Clipboard-Unterstützung gebaut wurde, ist im Normal-Modus auch "+p zum Einfügen aus der System-Zwischenablage möglich. reddit

Sicherheitshinweise

config.ini enthält Zugangsdaten und sollte nicht weitergegeben oder in öffentliche Repositories eingecheckt werden. Bei aktivierter Zwei-Faktor-Authentifizierung empfiehlt mailbox.org für externe Anwendungen App-Passwörter beziehungsweise Applikationspasswörter anstelle des normalen Passworts. kb.mailbox

Fehlersuche

Wenn der Cron-Job nicht läuft, sind die häufigsten Ursachen ein falscher Python-Pfad, fehlende Rechte auf Dateien oder abweichende Umgebungsvariablen unter Cron. Cron-Jobs sollten deshalb mit absoluten Pfaden arbeiten, und ein separates Log wie cron.log macht Fehler schnell sichtbar. betterstack

Wenn Termine nicht importiert werden, sollte zuerst geprüft werden, ob die IMAP-Anmeldung funktioniert, ob tatsächlich .ics-Anhänge im ausgewählten Ordner vorhanden sind und ob die CalDAV-URL exakt zum Zielkalender gehört. mailbox.org beschreibt, dass die Kalenderadresse direkt aus den Kalendereigenschaften des jeweiligen Kalenders übernommen werden soll. kb.mailbox

Empfohlener Betriebsmodus

Für dieses Setup ist ein stündlicher Cron-Job mit aktiviertem Duplikat-Schutz und unseen_only = true ein pragmatischer Standard. Das reduziert unnötige IMAP-Abfragen und passt gut zu einem Postfach, in dem Termine typischerweise per Mail-Anhang eingehen. naschenweng