231 lines
7.7 KiB
Markdown
231 lines
7.7 KiB
Markdown
# 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:45][cite:55]
|
|
|
|
## Überblick
|
|
|
|
Der Importer ist für ein einfaches, robustes Linux-Setup gedacht:
|
|
|
|
1. Das Skript verbindet sich per IMAP mit mailbox.org und durchsucht einen Ordner, standardmäßig `INBOX`.[cite:55][cite:338]
|
|
2. Nachrichten werden mit `BODY.PEEK[]` gelesen, damit sie beim Abruf nicht automatisch als gelesen markiert werden.[cite:338][cite:350]
|
|
3. `.ics`-Anhänge werden erkannt, per Hash gegen Doppelverarbeitung abgesichert und anschließend per CalDAV importiert.[cite:45][cite:162]
|
|
4. Nur Mails mit mindestens einem **erfolgreich importierten** ICS-Anhang werden optional als gelesen markiert; fehlgeschlagene oder irrelevante Mails bleiben ungelesen.[cite:340][cite:357]
|
|
|
|
## Projektstruktur
|
|
|
|
```text
|
|
ics-importer/
|
|
├── ics_mail_importer_env_v2.py
|
|
├── .env.example
|
|
├── .env
|
|
├── imported_uids.txt
|
|
├── ics_importer.log
|
|
├── cron.log
|
|
└── README.md
|
|
```
|
|
|
|
## Voraussetzungen
|
|
|
|
Benötigt werden:
|
|
|
|
- Linux
|
|
- Python 3
|
|
- `pipenv`
|
|
- Ein mailbox.org-Konto
|
|
- IMAP- und CalDAV-Zugang
|
|
- Bei aktiver Zwei-Faktor-Authentifizierung ein App- oder Applikationspasswort für externe Anwendungen.[cite:45][cite:55]
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
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 dem Skript als Umgebungsvariablen bereit.[cite:162][cite:164]
|
|
|
|
## Konfiguration mit `.env`
|
|
|
|
Beispiel für `.env.example`:
|
|
|
|
```dotenv
|
|
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=true
|
|
|
|
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` und Port `993`; die vollständige mailbox.org-E-Mail-Adresse wird als Benutzername verwendet.[cite:55]
|
|
|
|
Die vollständige CalDAV-URL des Zielkalenders wird in mailbox.org im Kalender über **Eigenschaften** angezeigt; mailbox.org verwendet dafür Adressen im Format `https://dav.mailbox.org/caldav/XXX`.[cite:45][cite:355]
|
|
|
|
Datei anlegen und schützen:
|
|
|
|
```bash
|
|
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:55] |
|
|
| `IMAP_PORT` | IMAP über SSL/TLS, normalerweise `993`.[cite:55] |
|
|
| `IMAP_USERNAME` | mailbox.org-E-Mail-Adresse.[cite:55] |
|
|
| `IMAP_PASSWORD` | Passwort oder App-Passwort. |
|
|
| `IMAP_FOLDER` | Zu prüfender Ordner, meist `INBOX`. |
|
|
| `IMAP_UNSEEN_ONLY` | Wenn `true`, werden nur ungelesene Nachrichten gesucht. |
|
|
| `IMAP_MARK_AS_READ` | Wenn `true`, werden nur erfolgreich verarbeitete ICS-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. |
|
|
|
|
## Verhalten beim Markieren als gelesen
|
|
|
|
Die aktuelle Skriptversion ist bewusst so gebaut, dass **nicht alle geprüften Mails** als gelesen markiert werden. Stattdessen gilt:
|
|
|
|
- Mails ohne ICS-Anhang bleiben unverändert.
|
|
- Mails mit ICS-Anhang bleiben ungelesen, wenn kein Termin erfolgreich importiert wurde.
|
|
- Nur Mails mit mindestens einem erfolgreich importierten ICS-Inhalt werden per `UID STORE` mit `\\Seen` markiert, sofern `IMAP_MARK_AS_READ=true` gesetzt ist.[cite:353][cite:357][cite:340]
|
|
|
|
Das Abrufen über `BODY.PEEK[]` verhindert, dass der Fetch selbst schon den `Seen`-Status setzt.[cite:350][cite:338]
|
|
|
|
## Python-Skript
|
|
|
|
Das Hauptskript heißt `ics_mail_importer_env_v2.py`. Es nutzt:
|
|
|
|
- `python-dotenv` für `.env`
|
|
- `imaplib` für IMAP
|
|
- `email` zum Parsen von Nachrichten und Anhängen
|
|
- `icalendar` zum Parsen von ICS-Dateien
|
|
- `caldav` für den Kalendereintrag auf mailbox.org.[cite:162][cite:338]
|
|
|
|
Beispielstart:
|
|
|
|
```bash
|
|
cd ~/ics-importer
|
|
pipenv run python3 ics_mail_importer_env_v2.py
|
|
```
|
|
|
|
## Erster Testlauf
|
|
|
|
Vor dem Einsatz mit Cron sollte das Skript immer einmal manuell getestet werden:
|
|
|
|
```bash
|
|
pipenv run python3 ics_mail_importer_env_v2.py
|
|
```
|
|
|
|
Dabei sollte geprüft werden:
|
|
|
|
- IMAP-Anmeldung funktioniert
|
|
- der richtige Ordner wird gelesen
|
|
- ICS-Anhänge werden erkannt
|
|
- Termine landen im gewünschten mailbox.org-Kalender
|
|
- nur erfolgreich verarbeitete ICS-Mails werden als gelesen markiert
|
|
|
|
## Cron-Einrichtung
|
|
|
|
Interpreter-Pfad aus `pipenv` ermitteln:
|
|
|
|
```bash
|
|
cd ~/ics-importer
|
|
pipenv --py
|
|
```
|
|
|
|
Beispiel für stündliche Ausführung:
|
|
|
|
```cron
|
|
0 * * * * /home/hans/.local/share/virtualenvs/ics-importer-wOz4rK-o/bin/python /home/hans/ics-importer/ics_mail_importer_env_v2.py >> /home/hans/ics-importer/cron.log 2>&1
|
|
```
|
|
|
|
Die User-Crontab wird mit `crontab -e` gepflegt. Für stündliche Jobs sind `0 * * * *` oder `@hourly` die üblichen Varianten.
|
|
|
|
## Logrotation
|
|
|
|
Wenn `cron.log` verwendet wird, sollte die Datei per `logrotate` rotiert werden. Beispiel für `/etc/logrotate.d/ics-importer`:
|
|
|
|
```conf
|
|
/home/hans/ics-importer/cron.log {
|
|
weekly
|
|
rotate 4
|
|
compress
|
|
delaycompress
|
|
missingok
|
|
notifempty
|
|
create 0644 hans hans
|
|
}
|
|
```
|
|
|
|
Diese Konfiguration rotiert wöchentlich, hält vier alte Versionen vor und komprimiert ältere Logs.
|
|
|
|
## Thunderbird und mailbox.org
|
|
|
|
Thunderbird ist für dieses Projekt nicht zwingend nötig, aber mailbox.org empfiehlt IMAP für Mail und CalDAV für Kalender.[cite:45][cite:55]
|
|
|
|
### IMAP in Thunderbird
|
|
|
|
Thunderbird erkennt mailbox.org häufig automatisch; IMAP ist der empfohlene Modus.[cite:55]
|
|
|
|
### CalDAV in Thunderbird
|
|
|
|
Kalender lassen sich in Thunderbird über **Datei → Neu → Kalender → Im Netzwerk → CalDAV** einbinden. Die vollständige CalDAV-Adresse ist in mailbox.org beim Kalender über **Eigenschaften** sichtbar.[cite:45][cite:355]
|
|
|
|
Falls erforderlich, kann in Thunderbird zusätzlich `calendar.network.multirealm=true` gesetzt werden, um Authentifizierungsprobleme zu vermeiden.[cite:45][cite:64]
|
|
|
|
## Sicherheit
|
|
|
|
`.env` enthält Zugangsdaten im Klartext und darf nicht öffentlich geteilt oder in Git eingecheckt werden. `python-dotenv` ist für lokale Konfiguration gedacht, ersetzt aber kein zentrales Secret-Management.[cite:162][cite:164]
|
|
|
|
Empfehlungen:
|
|
|
|
- `.env` nur lokal speichern
|
|
- `chmod 600 .env` setzen
|
|
- `.env` in `.gitignore` eintragen
|
|
- bei aktiver 2FA App-/Applikationspasswörter verwenden.[cite:45][cite:55]
|
|
|
|
## Fehlersuche
|
|
|
|
### IMAP funktioniert nicht
|
|
|
|
Prüfen:
|
|
|
|
- `IMAP_HOST=imap.mailbox.org`
|
|
- `IMAP_PORT=993`
|
|
- vollständige E-Mail-Adresse als Benutzername
|
|
- App-Passwort bei aktiver 2FA
|
|
- richtiger Ordner in `IMAP_FOLDER`.[cite:55]
|
|
|
|
### CalDAV funktioniert nicht
|
|
|
|
Prüfen:
|
|
|
|
- vollständige CalDAV-URL aus den Kalendereigenschaften
|
|
- richtiger Benutzername
|
|
- Passwort oder Applikationspasswort
|
|
- Schreibrechte auf den Zielkalender.[cite:45][cite:355]
|
|
|
|
### Mail wird zu früh als gelesen markiert
|
|
|
|
Die Version `ics_mail_importer_env_v2.py` verwendet `BODY.PEEK[]`, damit das bloße Abrufen den `Seen`-Status nicht verändert. Das Lesen-Markieren erfolgt erst danach gezielt per `UID STORE`, und nur wenn der Import erfolgreich war.[cite:338][cite:350][cite:357]
|
|
|
|
## Empfohlener Betriebsmodus
|
|
|
|
Für die meisten Setups ist diese Kombination sinnvoll:
|
|
|
|
- `IMAP_UNSEEN_ONLY=true`
|
|
- `IMAP_MARK_AS_READ=true`
|
|
- stündliche Ausführung per Cron
|
|
- Duplikat-Schutz über `imported_uids.txt`
|
|
|
|
Damit werden nur neue Nachrichten geprüft, unnötige Doppelimporte vermieden und nur tatsächlich erfolgreich verarbeitete ICS-Mails als gelesen markiert.
|