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: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.