104 lines
4.6 KiB
Markdown
104 lines
4.6 KiB
Markdown
# JARVIS E-Mail-Integration (Phase 4f) - Design
|
|
|
|
**Datum:** 2026-09-13
|
|
**Status:** Approved, bereit fuer Implementierungsplan
|
|
|
|
## Kontext
|
|
|
|
Naechste Integration nach Wetter (n8n-Cache) und Kalender (direktes CalDAV
|
|
Tool-Use): Zugriff auf das Postfach `kontakt@mbo-tech-it.de`. JARVIS soll
|
|
E-Mails lesen/zusammenfassen koennen (Chat, live) und - nach Bestaetigung -
|
|
E-Mails versenden koennen, plus ein Dashboard-Widget fuer neu eingegangene
|
|
Mails (n8n-Cache, wie beim Wetter).
|
|
|
|
**Zugangsdaten verifiziert (13.09.2026):**
|
|
- IMAP: `mx2f35.netcup.net:143`, STARTTLS, User `kontakt@mbo-tech-it.de`
|
|
(Login + INBOX-Zugriff erfolgreich getestet, 14 vorhandene Nachrichten)
|
|
- SMTP: `mx2f35.netcup.net:465`, implizites SSL/TLS, gleiche Zugangsdaten
|
|
(Login erfolgreich getestet, kein Test-Versand)
|
|
- Passwort ist woertlich `E%21gq10i` (kein URL-encodetes `!` - beide
|
|
Interpretationen getestet, nur die woertliche Variante funktioniert)
|
|
|
|
## Sicherheit: Versand nur nach Bestaetigung
|
|
|
|
`kontakt@mbo-tech-it.de` ist die offizielle Firmenadresse. Nach aussen
|
|
versendete E-Mails sind schwerer zu widerrufen als ein interner
|
|
Kalendereintrag. Deshalb - analog zum Kalender-Loeschen -: der System-Prompt
|
|
weist Claude an, vor jedem `send_email`-Aufruf Empfaenger/Betreff/Text im
|
|
Chat zur Bestaetigung vorzulegen und das Tool erst nach Zustimmung
|
|
aufzurufen.
|
|
|
|
## Architektur: zwei Wege, wie beim Kalender/Wetter kombiniert
|
|
|
|
**Chat (live, wie beim Kalender):** Zwei neue Claude-Tools in
|
|
`run_chat_completion`:
|
|
- `list_recent_emails(limit)` - liest live per IMAP (`imaplib`, Python-
|
|
Standardbibliothek, keine neue Abhaengigkeit) die letzten N Nachrichten
|
|
aus INBOX (nur Header: From/Subject/Date, `BODY.PEEK[...]` damit der
|
|
ungelesen-Status nicht veraendert wird), gibt `{from, subject, date,
|
|
unread}` pro Mail zurueck. Betreffzeilen werden mit
|
|
`email.header.decode_header` dekodiert (RFC 2047, z.B. `=?utf-8?B?...?=`).
|
|
- `send_email(to, subject, body)` - versendet per SMTP (`smtplib`,
|
|
Standardbibliothek) ueber Port 465 (implizites TLS). Nur nach
|
|
Chat-Bestaetigung aufzurufen (siehe oben).
|
|
|
|
**Dashboard-Widget (gecacht, wie beim Wetter):** Neuer n8n-Workflow mit dem
|
|
eingebauten Trigger-Node `Email Trigger (IMAP)`
|
|
(`n8n-nodes-base.emailReadImap`, verifiziert vorhanden in dieser
|
|
n8n-Version), der selbststaendig neue Nachrichten erkennt (kein eigener
|
|
Schedule-Trigger noetig, das uebernimmt der Node):
|
|
- `postProcessAction: "nothing"` - markiert Mails NICHT als gelesen, damit
|
|
das automatische Cachen den tatsaechlichen Lese-Status im Postfach nicht
|
|
verfaelscht
|
|
- `format: "simple"` reicht (nur Header/Text, keine Anhaenge noetig)
|
|
- Schreibt pro neuer Mail eine Zeile in eine neue Tabelle `email_cache`
|
|
(sender, subject, received_at)
|
|
|
|
`GET /api/v1/emails` (geschuetzt wie alle anderen Routen) liest die
|
|
neuesten Zeilen daraus fuer das Dashboard-Widget "Neue E-Mails".
|
|
|
|
## Datenmodell
|
|
|
|
```sql
|
|
CREATE TABLE email_cache (
|
|
id SERIAL PRIMARY KEY,
|
|
sender VARCHAR(255) NOT NULL,
|
|
subject VARCHAR(500) NOT NULL,
|
|
received_at TIMESTAMP NOT NULL,
|
|
cached_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
|
|
CREATE INDEX idx_email_cache_received_at ON email_cache(received_at);
|
|
```
|
|
|
|
Nur Metadaten (Absender/Betreff/Datum) werden dauerhaft gespeichert - keine
|
|
E-Mail-Inhalte/Volltexte, um die Menge an gespeicherter Geschaeftskorrespondenz
|
|
gering zu halten (die Chat-Tools lesen bei Bedarf live, ohne Zwischenspeicherung).
|
|
|
|
## Fehlerbehandlung
|
|
|
|
- IMAP/SMTP nicht erreichbar oder Login fehlgeschlagen: Chat-Tools werfen
|
|
eine Exception mit klarer Meldung, die als `tool_result` mit
|
|
`is_error: true` an Claude zurueckgeht (gleiches Muster wie beim Kalender).
|
|
- `GET /api/v1/emails` bei leerem Cache: gibt ein leeres Array zurueck (kein
|
|
503) - anders als beim Wetter ist "noch keine neue Mail seit Start des
|
|
Workflows" ein normaler, kein Fehlerzustand.
|
|
|
|
## Testing
|
|
|
|
- Backend: Unit-Tests fuer die IMAP-Parsing-Funktion (RFC-2047-Betreffs
|
|
dekodieren, unread-Flag aus FLAGS-Antwort ableiten) und fuer den
|
|
SMTP-Sende-Aufruf, jeweils mit gemocktem `imaplib`/`smtplib`.
|
|
- Manueller End-to-End-Test nach Deployment: Chat nach "was ist neu im
|
|
Postfach?" fragen (echte IMAP-Daten), eine Test-Mail an die eigene
|
|
Adresse per Chat versenden lassen (inkl. Bestaetigungs-Dialog), n8n-
|
|
Workflow aktivieren und pruefen, dass die Test-Mail in `email_cache`
|
|
auftaucht, Dashboard-Widget ansehen.
|
|
|
|
## Out of Scope (bewusst nicht Teil dieser Phase)
|
|
|
|
- Anhaenge (weder lesen noch versenden).
|
|
- Antworten/Weiterleiten als eigene Aktion (nur neues `send_email`).
|
|
- Loeschen/Verschieben von E-Mails.
|
|
- Mehrere Postfaecher/Ordner (nur INBOX von kontakt@mbo-tech-it.de).
|