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