feat: Gitea Webhook, IMAP, Settings & Deployment docs

- Webhook route and Gitea integration - IMAP service and Nextcloud/Porkbun setup docs - Settings UI improvements and API updates - SSH/Webhook fix prompt for emailsorter.webklar.com - Bootstrap, config and AI sorter updates
2026-01-31 15:00:00 +01:00
parent 7e7ec1013b
commit cbb225c001
24 changed files with 2173 additions and 32 deletions
--- a/docs/deployment/GITEA_WEBHOOK_SETUP.md
+++ b/docs/deployment/GITEA_WEBHOOK_SETUP.md
@@ -146,7 +146,19 @@ tail -f server/logs/webhook.log
 - ✅ Prüfe, ob der Server erreichbar ist (`curl https://emailsorter.webklar.com/api/webhook/status`)
 - ✅ Prüfe Gitea-Logs: **Settings** → **Webhooks** → **Delivery Log**

-### "Ungültige Webhook-Signatur" (401)
+### 502 Bad Gateway (von nginx)
+
+Nginx meldet 502, wenn das Backend (Node/PM2) nicht antwortet oder abstürzt.
+
+- ✅ **Backend läuft:** `pm2 list` – Prozess muss „online“ sein
+- ✅ **Backend neu starten:** `pm2 restart all` oder `pm2 start ecosystem.config.js`
+- ✅ **Logs prüfen:** `pm2 logs` – beim nächsten „Test Push“ sofort Fehler ansehen
+- ✅ **Health prüfen:** `curl -s -o /dev/null -w "%{http_code}" https://emailsorter.webklar.com/api/health` → sollte `200` sein
+- ✅ **Nginx-Upstream:** `proxy_pass` muss auf den richtigen Port zeigen (z. B. `http://127.0.0.1:3000`)
+
+Nach einem Code-Deploy (größeres Body-Limit, robustere Fehlerbehandlung) Backend neu starten: `pm2 restart all`.
+
+### "Ungültige Webhook-Signatur" (401/403)

 - ✅ Prüfe, ob `GITEA_WEBHOOK_SECRET` in `server/.env` gesetzt ist
 - ✅ Prüfe, ob das Secret in Gitea **genau gleich** ist (keine Leerzeichen!)
--- a/docs/deployment/SSH-WEBHOOK-FIX-PROMPT.md
+++ b/docs/deployment/SSH-WEBHOOK-FIX-PROMPT.md
@@ -0,0 +1,41 @@
+# Anleitung für SSH – nur EmailSorter (emailsorter.webklar.com) fixen
+
+**Kopiere den folgenden Abschnitt und schick ihn an die Person am Server (oder nutze ihn als eigene Checkliste):**
+
+---
+
+## Kontext
+
+- **Nur diese Website:** **emailsorter.webklar.com** (EmailSorter / Gitea-Webhook).
+- **Nicht anfassen:** Alle anderen Websites/Projekte auf dem gleichen Server.
+- **Problem:** Beim Gitea-Webhook („Test Push Event“) kommt **502 Bad Gateway** von nginx. Das Backend (Node/PM2) für emailsorter.webklar.com soll geprüft und ggf. neu gestartet werden.
+
+## Was ich brauche
+
+1. **PM2 prüfen (nur für EmailSorter):**
+   - `pm2 list` ausführen.
+   - Den Prozess finden, der zu **emailsorter.webklar.com** / EmailSorter gehört (Name oder Script-Pfad wie `server/index.mjs` oder `emailsorter`).
+   - Prüfen: Läuft er (Status „online“)? Wenn „stopped“ oder „errored“: das ist wahrscheinlich die Ursache für den 502.
+
+2. **Backend für EmailSorter neu starten:**
+   - Nur den PM2-Prozess für EmailSorter neu starten (nicht `pm2 restart all`, wenn andere Sites davon betroffen wären).
+   - Beispiel, wenn der Prozess „emailsorter“ heißt: `pm2 restart emailsorter`
+   - Oder nur den einen Eintrag in der Liste per Name/ID neu starten.
+
+3. **Env für EmailSorter prüfen (optional, nur wenn Webhook weiter 502/401 gibt):**
+   - In das Projektverzeichnis von EmailSorter wechseln (z. B. `/var/www/emailsorter` oder wo auch immer es liegt).
+   - Prüfen, ob in `server/.env` (oder im Root-`.env`) steht:  
+     `GITEA_WEBHOOK_SECRET=<dein Webhook-Secret>`  
+   - Wenn nicht: diese Zeile in der richtigen `.env` ergänzen (Secret bekommst du separat / steht in Gitea unter Webhook → Secret). Danach nur den EmailSorter-PM2-Prozess neu starten.
+
+4. **Kurz testen:**
+   - `curl -s -o /dev/null -w "%{http_code}" https://emailsorter.webklar.com/api/health`  
+     Sollte `200` ausgeben.
+   - `curl -s -o /dev/null -w "%{http_code}" https://emailsorter.webklar.com/api/webhook/status`  
+     Sollte ebenfalls `200` ausgeben.
+
+5. **Nichts anderes ändern:** Keine anderen Projekte, keine globalen nginx-/System-Konfigurationen anpassen – nur EmailSorter (emailsorter.webklar.com) wie oben beschrieben.
+
+---
+
+**Wenn du den Code gerade neu deployed hast (git pull für EmailSorter):** Danach bitte nur den PM2-Prozess für EmailSorter neu starten (z. B. `pm2 restart <name-oder-id>`), damit die neuen Webhook-Fixes aktiv sind.
--- a/docs/deployment/WEBHOOK_QUICK_START.md
+++ b/docs/deployment/WEBHOOK_QUICK_START.md
@@ -27,8 +27,9 @@ USE_PM2=true
 1. Gehe zu deinem Repository → **Settings** → **Webhooks**
 2. Klicke **Add Webhook** → **Gitea**
 3. Fülle aus:
-   - **Target URL:** `https://emailsorter.webklar.com/api/webhook/gitea`
+   - **Target URL:** `https://emailsorter.webklar.com/api/webhook/gitea` (Produktion)
   - **Secret:** `dein_generiertes_secret_hier` (aus Schritt 1)
+   - **Authorization Header (optional):** `Bearer dein_generiertes_secret_hier` (gleicher Wert wie Secret)
   - **Trigger On:** ✅ **Push Events**
   - **Branch Filter:** `main` oder `master`
 4. Klicke **Add Webhook**
--- a/docs/development/IMAP_IMPLEMENTATION_PLAN.md
+++ b/docs/development/IMAP_IMPLEMENTATION_PLAN.md
@@ -0,0 +1,183 @@
+# Implementierungsplan: IMAP / Porkbun / Nextcloud
+
+Plan, um EmailSorter um einen **IMAP-Provider** (z. B. Porkbun) zu erweitern. Dann funktioniert die Sortierung auch für Postfächer, die in Nextcloud Mail genutzt werden.
+
+---
+
+## Übersicht
+
+| Phase | Inhalt | Aufwand (grobe Schätzung) |
+|-------|--------|----------------------------|
+| **1** | IMAP-Bibliothek + Service-Grundgerüst | 1–2 h |
+| **2** | Datenbank + Connect-Route für IMAP | 1 h |
+| **3** | Sortier-Logik für IMAP (Ordner statt Labels) | 2–3 h |
+| **4** | Frontend: IMAP-Verbindung anlegen | 1–2 h |
+| **5** | Testen, Feinschliff, Doku | 1 h |
+
+---
+
+## Phase 1: IMAP-Bibliothek und Service
+
+**Ziel:** Backend kann sich per IMAP (z. B. Porkbun) verbinden, INBOX auflisten und E-Mails lesen.
+
+### 1.1 Abhängigkeit hinzufügen
+
+- **Datei:** `server/package.json`
+- **Aktion:** Dependency `imapflow` hinzufügen (moderner IMAP-Client für Node, SSL-Support).
+- **Befehl:** `npm install imapflow` im Ordner `server/`.
+
+### 1.2 Neuer Service
+
+- **Datei (neu):** `server/services/imap.mjs`
+- **Inhalt (Kern-Interface):**
+  - **Konstruktor:** `ImapService({ host, port, secure, user, password })` – z. B. für Porkbun: `host: 'imap.porkbun.com', port: 993, secure: true`.
+  - **connect()** – Verbindung aufbauen (login).
+  - **listEmails(maxResults, fromSeq?)** – Nachrichten aus INBOX (z. B. per FETCH ENVELOPE), Rückgabe: `{ messages: [{ id, uid, ... }], nextSeq }`.
+  - **getEmail(messageId)** bzw. **batchGetEmails(ids)** – eine bzw. mehrere Mails laden, Rückgabe-Format wie Gmail/Outlook: `{ id, headers: { from, subject }, snippet }`.
+  - **close()** – Verbindung sauber trennen (LOGOUT).
+- **Hinweis:** IMAP nutzt oft UID oder Sequence Number als „id“; einheitlich als `id` nach außen geben (String), damit die Sortier-Route wie bei Gmail/Outlook arbeitet.
+
+### 1.3 Akzeptanz Phase 1
+
+- Ein kleines Test-Script (z. B. `server/scripts/test-imap.mjs`) oder ein temporärer Route-Handler liest Umgebungsvariablen (IMAP_HOST, IMAP_PORT, IMAP_USER, IMAP_PASSWORD), baut `ImapService` auf, ruft `listEmails(10)` und `getEmail(...)` auf und loggt das Ergebnis. Keine Credentials im Repo – nur `.env` / Umgebungsvariablen.
+
+---
+
+## Phase 2: Datenbank und Connect-Route
+
+**Ziel:** Ein neuer Account-Typ „imap“ kann angelegt werden; Zugangsdaten werden gespeichert.
+
+### 2.1 Datenbank (Appwrite)
+
+- **Datei:** `server/bootstrap-v2.mjs` (oder separates Migrations-Script).
+- **Aktion:** In der Collection `email_accounts` optionale Attribute anlegen:
+  - `imapHost` (String, optional)
+  - `imapPort` (Integer, optional)
+  - `imapSecure` (Boolean, optional)
+- **Alternative (einfacher für nur Porkbun):** Keine neuen Felder; Host/Port im Code fest (imap.porkbun.com, 993). Dann nur `email` + Passwort nötig; Passwort in bestehendem Feld `accessToken` speichern (semantisch „geheimer Token für IMAP“). Für spätere andere IMAP-Server die optionalen Felder nachziehen.
+
+### 2.2 Connect-Route erweitern
+
+- **Datei:** `server/routes/email.mjs`
+- **Route:** `POST /api/email/connect` (bzw. die Route, die Accounts anlegt).
+- **Aktionen:**
+  - Im Validierungs-Schema `provider` um `'imap'` erweitern: z. B. `rules.isIn('provider', ['gmail', 'outlook', 'demo', 'imap'])`.
+  - Body für IMAP: mindestens `userId`, `provider: 'imap'`, `email`, `password` (oder `accessToken` als Passwort). Optional: `imapHost`, `imapPort`, `imapSecure`.
+  - Wenn `provider === 'imap'`:
+    - Host/Port/Secure aus Body oder Default (Porkbun: imap.porkbun.com, 993, true).
+    - Passwort nicht loggen; in DB in `accessToken` (oder neuem Feld) speichern.
+    - Optional: einmalig `ImapService` instanziieren, `connect()` + `listEmails(1)` aufrufen; bei Erfolg Account anlegen, sonst Fehler zurückgeben („Ungültige Anmeldedaten“).
+  - Account-Dokument anlegen mit `provider: 'imap'`, `email`, `accessToken` (= Passwort), ggf. `imapHost`, `imapPort`, `imapSecure`.
+
+### 2.3 Middleware/Validierung
+
+- **Datei:** `server/middleware/validate.mjs` (falls dort Regeln liegen) oder direkt in der Route.
+- **Aktion:** Für IMAP ggf. zusätzliche Felder erlauben: `imapHost`, `imapPort`, `imapSecure`, `password` (oder wie du das Feld nennst).
+
+### 2.4 Akzeptanz Phase 2
+
+- Per API-Client (Postman/curl) oder Frontend: POST mit `provider: 'imap'`, `email`, `password` (und optional Host/Port) an `/connect` senden. Erwartung: 201, Account in Appwrite mit `provider: 'imap'`. Bei falschem Passwort: 4xx mit verständlicher Meldung.
+
+---
+
+## Phase 3: Sortier-Logik für IMAP
+
+**Ziel:** `POST /api/email/sort` funktioniert für Accounts mit `provider === 'imap'`: E-Mails werden per KI kategorisiert und in IMAP-Ordner verschoben.
+
+### 3.1 Ordner-Mapping
+
+- **Konzept:** Kategorien (z. B. `vip`, `promotions`, `newsletters`, `archive`) auf Ordner-Namen mappen. Z. B.:
+  - `archive` / `archive_read` → Ordner `Archive` oder `EmailSorter/Archive`
+  - `promotions` → `Promotions` oder `EmailSorter/Promotions`
+  - usw.
+- **Datei:** Entweder in `server/services/imap.mjs` (Funktion `getFolderNameForCategory(category)`) oder in `server/services/ai-sorter.mjs` / Config. Einheitliche Liste (z. B. Objekt `categoryToFolder`) verwenden.
+
+### 3.2 IMAP-Service erweitern
+
+- **Datei:** `server/services/imap.mjs`
+- **Neue Methoden:**
+  - **ensureFolder(folderName)** – Ordner anlegen (CREATE), falls nicht vorhanden; Fehler „existiert bereits“ ignorieren.
+  - **moveToFolder(messageId, folderName)** – Nachricht aus INBOX in den Ordner verschieben (MOVE oder COPY + DELETE aus INBOX).
+  - Optional: **markAsRead(messageId)** – falls „archive_read“ = verschieben + als gelesen markieren.
+
+### 3.3 Sortier-Route erweitern
+
+- **Datei:** `server/routes/email.mjs`
+- **Stelle:** Dort, wo `account.provider === 'gmail'` und `=== 'outlook'` abgefragt werden (und Demo).
+- **Aktion:** Neuen Block `else if (account.provider === 'imap')` hinzufügen:
+  1. `ImapService` aus Account-Daten instanziieren (host, port, secure, user = email, password = accessToken).
+  2. `connect()`.
+  3. In einer Schleife (analog Gmail/Outlook):
+     - `listEmails(batchSize, nextSeq)` → Liste von Nachrichten.
+     - `batchGetEmails(ids)` → From, Subject, Snippet.
+     - Für jede E-Mail: KI-Kategorie ermitteln (bestehender `AISorterService`), dann `ensureFolder(categoryToFolder[category])` und `moveToFolder(id, folderName)`.
+     - Bei „archive_read“ ggf. zusätzlich als gelesen markieren.
+  4. Statistiken aktualisieren (wie bei Gmail/Outlook).
+  5. `close()` aufrufen.
+- **Fehlerbehandlung:** Bei IMAP-Fehlern (z. B. „Invalid credentials“) sinnvolle Meldung zurückgeben und ggf. Account als „reconnect nötig“ markieren.
+
+### 3.4 Akzeptanz Phase 3
+
+- Ein IMAP-Account ist verbunden. Aufruf von `POST /api/email/sort` mit `userId` und `accountId`. Erwartung: E-Mails aus INBOX werden kategorisiert und in die richtigen Ordner verschoben; Response enthält z. B. `sortedCount` und Kategorie-Statistiken. In Nextcloud Mail (oder anderem IMAP-Client) erscheinen die neuen Ordner und verschobenen Mails.
+
+---
+
+## Phase 4: Frontend – IMAP verbinden
+
+**Ziel:** Nutzer können im UI „Anderes Postfach (IMAP)“ wählen und E-Mail + Passwort eingeben.
+
+### 4.1 Verbindungs-Flow
+
+- **Datei(en):** Dort, wo heute Gmail/Outlook/Demo angeboten werden (z. B. Setup, Settings, „E-Mail verbinden“).
+- **Aktion:**
+  - Neue Option „IMAP / anderes Postfach“ (oder „Porkbun / eigenes Postfach“).
+  - Beim Klick: Formular anzeigen mit:
+    - E-Mail (Pflicht)
+    - Passwort / App-Passwort (Pflicht, Typ Passwort)
+    - Optional (z. B. für Power-User): Host, Port, SSL (Checkbox); Defaults: imap.porkbun.com, 993, SSL an.
+  - Submit: POST an Backend (z. B. `/api/email/connect`) mit `provider: 'imap'`, `email`, `password`, optional `imapHost`, `imapPort`, `imapSecure`.
+  - Bei Erfolg: Erfolgsmeldung, Account-Liste aktualisieren. Bei Fehler: Meldung anzeigen (z. B. „Anmeldung fehlgeschlagen – prüfe E-Mail und Passwort“).
+
+### 4.2 API-Client (Frontend)
+
+- **Datei:** z. B. `client/src/lib/api.ts`
+- **Aktion:** Methode `connectImapAccount(userId, { email, password, imapHost?, imapPort?, imapSecure? })` hinzufügen, die `POST /api/email/connect` mit diesen Daten aufruft.
+
+### 4.3 Akzeptanz Phase 4
+
+- Im UI „IMAP verbinden“ auswählen, E-Mail + Passwort eingeben, absenden. Account erscheint in der Account-Liste. Danach „Sortieren“ auslösbar und funktioniert wie in Phase 3.
+
+---
+
+## Phase 5: Testen und Doku
+
+- **Manuell:** Mit einem echten Porkbun-Account (oder anderem IMAP) verbinden, Sortierung ausführen, in Nextcloud prüfen, ob Ordner und Mails stimmen.
+- **Sicherheit:** Prüfen, dass Passwörter nirgends geloggt werden und nicht im Frontend gespeichert werden.
+- **Doku:** `docs/setup/IMAP_NEXTCLOUD_PORKBUN.md` ggf. um „Konfiguration Porkbun“ und „Troubleshooting“ ergänzen (z. B. App-Passwort, 2FA).
+
+---
+
+## Kurz-Checkliste
+
+- [x] Phase 1: `imapflow` installiert, `server/services/imap.mjs` mit connect, listEmails, getEmail, close; Test mit .env-Credentials.
+- [x] Phase 2: Appwrite `email_accounts` ggf. um IMAP-Felder erweitert; Connect-Route akzeptiert `imap` und speichert Zugangsdaten; Test: Account per API anlegen.
+- [x] Phase 3: Ordner-Mapping; ImapService: ensureFolder, moveToFolder; Sortier-Route: Block für `provider === 'imap'`; Test: Sortierung für IMAP-Account.
+- [x] Phase 4: Frontend-Option „IMAP“, Formular E-Mail/Passwort, API-Anbindung; Test: End-to-End Verbindung + Sortierung aus UI.
+- [ ] Phase 5: Manueller Test mit Porkbun/Nextcloud; Sicherheits-Check; Doku aktualisiert.
+
+---
+
+## Dateien-Übersicht
+
+| Aktion | Datei |
+|--------|--------|
+| Neu | `server/services/imap.mjs` |
+| Neu (optional) | `server/scripts/test-imap.mjs` |
+| Ändern | `server/package.json` (imapflow) |
+| Ändern | `server/bootstrap-v2.mjs` (optional: IMAP-Attribute) |
+| Ändern | `server/routes/email.mjs` (provider imap, connect + sort) |
+| Ändern | `server/middleware/validate.mjs` (falls nötig) |
+| Ändern | Frontend: Connect-UI (Setup/Settings) + `client/src/lib/api.ts` |
+| Ändern | `docs/setup/IMAP_NEXTCLOUD_PORKBUN.md` (Feinschliff) |
+
+Wenn du mit Phase 1 startest, reicht zunächst: `imapflow` einbinden und `imap.mjs` mit connect + listEmails + getEmail implementieren und lokal mit Porkbun testen.
--- a/docs/setup/IMAP_NEXTCLOUD_PORKBUN.md
+++ b/docs/setup/IMAP_NEXTCLOUD_PORKBUN.md
@@ -0,0 +1,189 @@
+# IMAP / Nextcloud / Porkbun – Integration
+
+## Ziel
+
+EmailSorter soll E-Mails nutzen, die über **Porkbun** (SMTP/IMAP) laufen und ggf. in **Nextcloud Mail** genutzt werden.
+
+**Porkbun (von dir genutzt):**
+
+| Dienst | Host | Port | Verschlüsselung |
+|--------|------|------|-----------------|
+| IMAP | imap.porkbun.com | 993 | SSL (SSL/TLS) |
+| SMTP | smtp.porkbun.com | 587 | STARTTLS |
+| SMTP (Alt.) | smtp.porkbun.com | 50587 | STARTTLS |
+| SMTP | smtp.porkbun.com | 465 | Implicit TLS |
+| POP | pop.porkbun.com | 995 | SSL (SSL/TLS) |
+
+Für **Sortieren/Lesen** reicht **IMAP** (993, SSL). SMTP wird nur zum Senden gebraucht; EmailSorter sortiert nur, also: IMAP-Anbindung ist der relevante Teil.
+
+---
+
+## Aktueller Stand in EmailSorter
+
+- **Unterstützt:** **Gmail** (OAuth), **Outlook** (OAuth), **IMAP** (E-Mail + Passwort/App-Passwort), **Demo** (Fake-Daten).
+- **IMAP:** Generischer IMAP-Provider ist implementiert; Standard ist Porkbun (`imap.porkbun.com`, 993, SSL), andere IMAP-Server über „Advanced“ (Host/Port/SSL) konfigurierbar.
+
+Ablauf:
+
+- **Gmail:** `GmailService(accessToken, refreshToken)` → Gmail API (messages.list, get, labels).
+- **Outlook:** `OutlookService(accessToken)` → Microsoft Graph (Mail API).
+- **IMAP:** `ImapService(host, port, secure, user, password)` → IMAP (INBOX lesen, Ordner anlegen, Mails verschieben).
+- **Demo:** feste Test-E-Mails, kein echter Zugriff.
+
+Accounts werden in `email_accounts` mit `provider`, `email`, `accessToken` (bei IMAP = Passwort), optional `imapHost`, `imapPort`, `imapSecure` gespeichert.
+
+---
+
+## Was „Nextcloud integrieren“ bedeuten kann
+
+1. **Nextcloud nur als Mail-Client**
+   - Nextcloud Mail nutzt im Hintergrund IMAP/SMTP (z. B. Porkbun).
+   - EmailSorter spricht **direkt mit dem gleichen IMAP-Server** (Porkbun), nicht mit Nextcloud.
+   - Nutzer verbindet in EmailSorter sein **Porkbun-Postfach** (IMAP: imap.porkbun.com, 993, E-Mail + App-Passwort).
+   - Dann: E-Mails, die in Nextcloud sichtbar sind, sind auch für EmailSorter über IMAP erreichbar – und umgekehrt (Sortierung über EmailSorter wirkt in Nextcloud, weil dasselbe Postfach).
+
+2. **Nextcloud als Identity/SSO**
+   - Würde bedeuten: Login bei EmailSorter über Nextcloud (OIDC/SAML). Das ist ein separates Thema (Auth), nicht die E-Mail-Sortierung.
+
+3. **Nextcloud Mail API**
+   - Theoretisch könnte man die Nextcloud Mail-API ansprechen; typischerweise nutzt man aber direkt IMAP, weil es einfacher und überall gleich ist.
+
+**Pragmatisch:** „In Nextcloud integrieren“ heißt hier: **IMAP-Provider in EmailSorter** so einbauen, dass du **Porkbun (IMAP)** verbinden kannst. Alles, was in Nextcloud über dieses Postfach läuft, wird damit automatisch mit EmailSorter synchron sein.
+
+---
+
+## Technisch: Was für IMAP (Porkbun) nötig ist
+
+### 1. Neuer Provider `imap`
+
+- In **Backend** (`server/routes/email.mjs`): `provider` um `'imap'` erweitern (z. B. neben `gmail`, `outlook`, `demo`).
+- Beim **Verbinden** eines Accounts: für IMAP keine OAuth-Tokens, sondern z. B.:
+  - `imapHost` (z. B. `imap.porkbun.com`)
+  - `imapPort` (993)
+  - `imapSecure` (true für SSL)
+  - `email` (Login = E-Mail-Adresse)
+  - Passwort/App-Passwort (sicher speichern, z. B. in einem bestehenden Token-Feld oder neuem verschlüsselten Feld)
+
+### 2. Datenbank (Appwrite) `email_accounts`
+
+- Optional neue Attribute, z. B.:
+  - `imapHost` (string)
+  - `imapPort` (integer)
+  - `imapSecure` (boolean)
+- Oder: für **nur Porkbun** Host/Port fest im Code (imap.porkbun.com, 993) und nur E-Mail + Passwort in DB speichern (z. B. in `accessToken` als Passwort, oder eigenes Feld).
+
+### 3. Neuer Service `server/services/imap.mjs`
+
+- **IMAP-Client** in Node (z. B. `imapflow` – gut für Node, SSL, modern).
+- Interface analog zu Gmail/Outlook:
+  - **listEmails(maxResults, pageToken)** → Liste von Nachrichten aus INBOX (UIDs/Seq + ggf. Envelope).
+  - **getEmail(messageId)** / **batchGetEmails(ids)** → From, Subject, Snippet (Body-Preview).
+  - **applySorting(messageId, category)** → bei IMAP: **Ordner** statt Labels (z. B. „Archive“, „Promotions“). D. h.:
+    - Ordner anlegen, falls nicht vorhanden (CREATE wenn nötig).
+    - Nachricht in den passenden Ordner **verschieben** (MOVE oder COPY + DELETE aus INBOX).
+- Gmail nutzt Labels; IMAP nutzt **Folders**. Die Logik „Kategorie X“ muss also auf „Folder X“ gemappt werden (z. B. `Archive`, `Promotions`, `Newsletter`).
+
+### 4. Sortier-Route `POST /api/email/sort`
+
+- Wenn `account.provider === 'imap'`:
+  - `ImapService` mit gespeicherten IMAP-Daten instanziieren.
+  - Wie bei Gmail/Outlook: E-Mails holen → KI kategorisieren → Aktionen anwenden. Bei IMAP: Aktion = „in Ordner X verschieben“ statt „Label setzen“.
+
+### 5. Frontend (Client)
+
+- Neue Option „E-Mail mit IMAP verbinden“ (z. B. „Anderes Postfach (IMAP)“).
+- Formular: E-Mail, App-Passwort; optional Host/Port (oder vorkonfiguriert für Porkbun).
+- Kein OAuth-Flow; nach Submit werden Zugangsdaten an das Backend geschickt, Backend speichert sie und testet die Verbindung (z. B. einmaliger LOGIN + SELECT INBOX + DISCONNECT).
+
+### 6. Sicherheit
+
+- Passwort/App-Passwort **niemals** im Frontend speichern; nur beim Verbinden einmal an Backend senden.
+- Im Backend: verschlüsselt oder in sicherem Secret-Storage ablegen (z. B. nur in DB, Zugriff nur server-seitig).
+
+---
+
+## Konfiguration in EmailSorter
+
+1. **Einstellungen → Accounts** (oder Setup-Seite: Link „Add your account in Settings → Accounts“).
+2. Auf **„IMAP / Other“** klicken – es öffnet sich ein Formular.
+3. **E-Mail** und **Passwort** (bzw. App-Passwort bei 2FA) eintragen.
+4. Optional **„Advanced (host, port, SSL)“** aufklappen:
+   - **IMAP host:** Standard `imap.porkbun.com` (für andere Anbieter z. B. `imap.gmail.com` oder Nextcloud-IMAP-Host).
+   - **Port:** Standard **993** (SSL).
+   - **Use SSL:** aktiviert lassen für 993.
+5. **„Connect IMAP“** klicken. Das Backend testet die Verbindung; bei Erfolg erscheint das Konto in der Account-Liste. Danach kann **„Sortieren“** wie bei Gmail/Outlook genutzt werden (E-Mails werden in IMAP-Ordner verschoben).
+
+---
+
+## So richtest du es in Nextcloud ein
+
+EmailSorter wird **nicht in Nextcloud installiert**. Beide nutzen **dasselbe Postfach per IMAP**: Nextcloud Mail als Client zum Lesen/Schreiben, EmailSorter zum automatischen Sortieren. Ordner und verschobene Mails sind in beiden sichtbar.
+
+### 1. In Nextcloud Mail: Postfach hinzufügen (falls noch nicht vorhanden)
+
+1. In Nextcloud einloggen → **Mail**-App öffnen.
+2. **Konto hinzufügen** (oder **Einstellungen** des Mail-Kontos).
+3. **E-Mail-Adresse** und **Passwort** (bzw. **App-Passwort** bei 2FA) eintragen.
+4. **IMAP-Server** manuell einstellen (nicht „Auto“), damit dieselben Werte wie in EmailSorter genutzt werden:
+   - **IMAP:**  
+     - Server: `imap.porkbun.com` (bzw. dein IMAP-Host)  
+     - Port: **993**  
+     - Verschlüsselung: **SSL/TLS**
+   - **SMTP** (zum Senden):  
+     - Server: `smtp.porkbun.com`  
+     - Port: **587** (STARTTLS) oder **465** (SSL)  
+     - Nutzer/Passwort wie IMAP
+5. Speichern. Das Postfach erscheint in Nextcloud Mail; du liest und schreibst wie gewohnt.
+
+### 2. In EmailSorter: dasselbe Postfach verbinden
+
+1. Bei **EmailSorter** einloggen (z. B. emailsorter.webklar.com).
+2. **Einstellungen → Accounts** → **„IMAP / Other“** klicken.
+3. **Gleiche E-Mail-Adresse** und **gleiches Passwort** (bzw. App-Passwort) wie in Nextcloud eintragen.
+4. Bei Porkbun reicht der Standard (**Advanced** geschlossen). Anderer Anbieter: **Advanced** öffnen und **IMAP-Host** (z. B. `imap.porkbun.com`), **Port 993**, **Use SSL** an setzen.
+5. **„Connect IMAP“** klicken. Wenn die Verbindung klappt, erscheint das Konto unter „Connected Email Accounts“.
+
+### 3. Nutzung
+
+- **Nextcloud Mail:** E-Mails lesen, schreiben, Ordner manuell nutzen – wie bisher.
+- **EmailSorter:** Im Dashboard **„Sortieren“** ausführen. EmailSorter liest die INBOX, kategorisiert per KI und **verschiebt** Mails in Ordner (z. B. Archive, Promotions, Newsletter).
+- **In Nextcloud:** Diese Ordner und die verschobenen Mails erscheinen automatisch, weil dasselbe IMAP-Postfach genutzt wird. Gegebenenfalls Mail-App aktualisieren oder kurz warten, bis die Ordnerliste neu geladen ist.
+
+Es ist **keine Installation oder App in Nextcloud** nötig – nur dasselbe Konto in Nextcloud Mail (IMAP) und in EmailSorter (IMAP) einrichten.
+
+---
+
+## Porkbun-spezifisch (kurz)
+
+- **IMAP:** `imap.porkbun.com`, Port **993**, SSL.
+- **Login:** volle E-Mail-Adresse + Passwort oder **App-Passwort** (wenn 2FA aktiv).
+- In EmailSorter: Provider **IMAP** mit Standard Host/Port für Porkbun; andere IMAP-Server über „Advanced“ einstellbar.
+
+---
+
+## Troubleshooting
+
+- **„Login failed – check email and password“**  
+  - E-Mail-Adresse exakt wie beim Anbieter (Groß-/Kleinschreibung bei manchen Servern relevant).  
+  - Bei **2FA (Porkbun/Provider):** normales Passwort reicht oft nicht – **App-Passwort** in den Account-Einstellungen des Anbieters erzeugen und dieses im EmailSorter-Formular eintragen.
+
+- **Verbindung baut nicht auf (Timeout / SSL-Fehler)**  
+  - Port **993** und **Use SSL** aktiviert für TLS.  
+  - Firewall/Netzwerk: ausgehende Verbindung zu `imap.porkbun.com:993` erlauben.  
+  - Bei eigenem IMAP-Server: Host/Port in „Advanced“ prüfen (z. B. 143 nur mit STARTTLS, nicht „Use SSL“ im gleichen Sinne – bei Zweifel 993 + SSL verwenden).
+
+- **Sortierung läuft, Ordner erscheinen in Nextcloud nicht**  
+  - Nextcloud Mail nutzt dasselbe IMAP-Postfach; Ordner sollten nach kurzer Zeit sichtbar sein. Mail-App ggf. aktualisieren oder Abo des Postfachs prüfen.
+
+---
+
+## Reihenfolge der Umsetzung (Vorschlag)
+
+1. **IMAP-Bibliothek** im Backend (z. B. `imapflow`) einbinden.
+2. **`server/services/imap.mjs`** implementieren: connect, listEmails, getEmail, moveToFolder, createFolder.
+3. **DB/Bootstrap:** `email_accounts` um IMAP-Felder erweitern (oder Nutzung bestehender Felder definieren).
+4. **Route `/connect`:** für `provider: 'imap'` Host/Port/User/Passwort entgegennehmen und Account anlegen.
+5. **Route `/sort`:** für `provider === 'imap'` die gleiche Sortier-Pipeline wie bei Gmail/Outlook, aber mit `ImapService` und Ordner-Verschiebung statt Labels.
+6. **Frontend:** Verbindungs-UI für IMAP (E-Mail + Passwort, ggf. Host/Port).
+
+Wenn du willst, kann als Nächstes ein konkreter Implementierungsplan (mit Dateinamen und API-Skizzen) oder ein kleines Proof-of-Concept nur für „Connect + Liste INBOX“ für Porkbun-IMAP ausgearbeitet werden.