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
This commit is contained in:
189
docs/setup/IMAP_NEXTCLOUD_PORKBUN.md
Normal file
189
docs/setup/IMAP_NEXTCLOUD_PORKBUN.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user