Initial commit: IMAP Mail Filter Service

2026-03-19 13:02:44 +01:00
parent 44fb27801d
commit 61c4384111
34 changed files with 2345 additions and 0 deletions
@@ -0,0 +1,156 @@
+# IMAP Mail Filter Service
+
+Ein Docker-basierter Service, der E-Mail-Filterregeln unabhängig vom Mail-Client ausführt. Egal ob du Evolution, Thunderbird oder einen anderen Client nutzt — die Filter laufen einfach weiter.
+
+## Features
+
+- **Mehrere IMAP-Konten** verwalten
+- **Filterregeln** mit flexiblen Bedingungen (Von, An, Betreff, Text)
+- **Matching**: enthält, exakt, Regex — jeweils mit Negierung
+- **Aktionen**: Verschieben, Weiterleiten, Löschen, Als gelesen markieren
+- **Web-UI** zur Verwaltung von Konten und Regeln
+- **YAML Import/Export** für portable Konfiguration
+- **Passwort-Verschlüsselung** mit Fernet
+- **Konfigurierbares Polling-Intervall** pro Konto
+
+## Schnellstart
+
+### 1. `.env` erstellen
+
+```bash
+cp .env.example .env
+```
+
+Encryption-Key generieren und in die `.env` eintragen:
+
+```bash
+python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+Falls `cryptography` noch nicht installiert ist:
+
+```bash
+pip install cryptography
+python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+Den ausgegebenen Key in die `.env` eintragen:
+
+```
+ENCRYPTION_KEY=dein-generierter-key-hier
+```
+
+### 2. Mit Docker starten
+
+```bash
+docker-compose up --build
+```
+
+Der Service ist dann unter **http://localhost:8080** erreichbar.
+
+### 3. Ohne Docker (lokal)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --reload
+```
+
+Erreichbar unter **http://localhost:8000**.
+
+## Benutzung
+
+### Web-UI
+
+- **Dashboard** (`/`) — Übersicht aller Konten mit Status und Quick-Actions
+- **Konten** (`/accounts`) — IMAP-Konten anlegen, bearbeiten, Verbindungstest
+- **Filter** (`/filters`) — Filterregeln pro Konto erstellen und verwalten
+- **YAML** (`/yaml`) — Konfiguration exportieren und importieren
+
+### REST-API
+
+| Endpunkt | Beschreibung |
+|---|---|
+| `GET /api/accounts/` | Alle Konten auflisten |
+| `POST /api/accounts/` | Neues Konto anlegen |
+| `PUT /api/accounts/{id}` | Konto bearbeiten |
+| `DELETE /api/accounts/{id}` | Konto löschen |
+| `POST /api/accounts/{id}/test` | IMAP-Verbindungstest |
+| `POST /api/accounts/{id}/poll-now` | Sofort nach neuen Mails prüfen |
+| `GET /api/filters/account/{id}` | Filterregeln eines Kontos |
+| `POST /api/filters/` | Neue Filterregel |
+| `PUT /api/filters/{id}` | Filterregel bearbeiten |
+| `DELETE /api/filters/{id}` | Filterregel löschen |
+| `GET /api/yaml/export` | Konfiguration als YAML |
+| `POST /api/yaml/import` | YAML-Datei importieren |
+
+### YAML-Konfiguration
+
+Filterregeln können auch direkt als YAML definiert werden. Passwörter lassen sich als Umgebungsvariablen referenzieren:
+
+```yaml
+accounts:
+  - name: "Arbeit"
+    imap_host: "imap.example.com"
+    imap_port: 993
+    use_ssl: true
+    username: "user@example.com"
+    password: "${WORK_IMAP_PW}"
+    poll_interval_seconds: 120
+    filters:
+      - name: "Newsletter sortieren"
+        priority: 10
+        source_folder: "INBOX"
+        stop_processing: true
+        conditions:
+          - field: "from"
+            match_type: "contains"
+            value: "newsletter@"
+        actions:
+          - action_type: "move"
+            parameter: "Newsletter"
+```
+
+Beim Start wird `config/filters.yaml` automatisch importiert (konfigurierbar via `YAML_SYNC_ON_STARTUP`).
+
+## Umgebungsvariablen
+
+| Variable | Standard | Beschreibung |
+|---|---|---|
+| `ENCRYPTION_KEY` | *(leer)* | Fernet-Key für Passwort-Verschlüsselung |
+| `LOG_LEVEL` | `INFO` | Log-Level (DEBUG, INFO, WARNING, ERROR) |
+| `YAML_SYNC_ON_STARTUP` | `true` | YAML-Datei beim Start importieren |
+| `DATABASE_URL` | `sqlite:///data/mailfilter.db` | Datenbank-Pfad |
+
+## Projektstruktur
+
+```
+├── app/
+│   ├── main.py              # FastAPI App + Web-Routen
+│   ├── config.py             # Konfiguration via Umgebungsvariablen
+│   ├── database.py           # SQLAlchemy Setup
+│   ├── models/db_models.py   # Datenbank-Modelle
+│   ├── schemas/schemas.py    # API Request/Response Schemas
+│   ├── routers/              # REST-API Endpunkte
+│   ├── services/
+│   │   ├── imap_client.py    # IMAP-Verbindung und Mail-Aktionen
+│   │   ├── filter_engine.py  # Regelauswertung
+│   │   ├── scheduler.py      # Polling-Scheduler
+│   │   ├── yaml_service.py   # YAML Import/Export
+│   │   └── encryption.py     # Passwort-Verschlüsselung
+│   ├── templates/            # Jinja2 HTML-Templates
+│   └── static/               # CSS + JS
+├── config/filters.yaml       # YAML-Filterkonfiguration
+├── data/                     # SQLite-Datenbank (Docker Volume)
+├── docker-compose.yml
+├── Dockerfile
+└── requirements.txt
+```
+
+## Tests
+
+```bash
+source .venv/bin/activate
+python -m pytest tests/ -v
+```