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

```text
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:

```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 als Umgebungsvariablen bereit.[cite:162][cite:164]

## Konfiguration mit `.env`

Eine `.env.example` kann als Vorlage verwendet werden:

```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=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:

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

```bash
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:

```bash
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:

```bash
cd ~/ics-importer
pipenv --py
```

Stündlicher Cron-Eintrag:

```cron
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:

```conf
/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.