Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M09-email-inbox.md
T

570 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
module: 9
title: Email Inbox + Sync (Gmail/Outlook)
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: requirements-pur
---
# Modul 9 — Email Inbox + Sync
> **Detail-Spec gemäß LP-9.** Verbindet die Mailbox(en) eines Tenants (Gmail / Outlook) mit dem CRM. Jede eingehende Mail wird mit Kontakten/Deals/Projekten verknüpft und im Activity-Stream sichtbar. Liefert das Sending-Domain-Fundament (DKIM/SPF/DMARC) für Modul 10. Bildet zusammen mit M10 die Ablöse-Komponente für HubSpot-Mail-Tools (LP-7).
## Themenblöcke
```
A. Datenmodell
B. Mailbox-Connect (OAuth Gmail / Microsoft)
C. Sending-Domain (DKIM/SPF/DMARC) als Plattform-Fundament
D. Sync-Strategie (Push-Webhooks statt Polling)
E. Auto-Match-Logik (Mail → Kontakt / Deal / Projekt)
F. Inbox-View (Liste + Detail)
G. Outbound-Compose
H. Activity-Stream-Integration
I. Permissions
J. Provider-Adapter (LP-11)
K. Phase 2
```
---
## Block A — Datenmodell
### EmailIntegrationMailbox
Pro Tenant-User eine verbundene Mailbox. Tenant-scoped (RLS).
- `id`, `tenant_id`, `created_at`, `updated_at`
- `owner_user_id` (FK auf TenantUser — wem gehört die Mailbox)
- `provider` (Enum: `gmail | microsoft`)
- `email_address` (unique pro Tenant)
- `display_name`
- `oauth_access_token_encrypted`, `oauth_refresh_token_encrypted`, `oauth_token_expires_at`
- `oauth_scope_granted` (Liste der gewährten Scopes)
- `sync_status` (Enum: `connecting | active | paused | error | revoked`)
- `last_sync_at`, `last_error_text`
- `webhook_subscription_id` (Provider-spezifisch — Gmail: Pub/Sub-Topic, Microsoft: Subscription-ID)
- `webhook_expires_at` (Microsoft-Subscriptions laufen nach 3 Tagen ab → Renewal-Job)
- `is_default_for_user` (Boolean — falls User mehrere Mailboxen hat)
- `archived_at`
**Indizes:** `(tenant_id, owner_user_id)`, `(tenant_id, email_address)`, `(sync_status, webhook_expires_at)` für Renewal-Worker.
### EmailIntegrationMessage
Spiegel der Mails aus der angebundenen Mailbox. Tenant-scoped.
- `id`, `tenant_id`, `mailbox_id`, `created_at`
- `provider_message_id` (Gmail-`id` / Microsoft-`internetMessageId`) — unique pro Mailbox
- `provider_thread_id` (Gmail-`threadId` / Microsoft-`conversationId`)
- `direction` (Enum: `inbound | outbound`)
- `from_address`, `from_name`
- `to_addresses[]`, `cc_addresses[]`, `bcc_addresses[]`
- `subject`
- `body_html`, `body_text`
- `received_at`, `sent_at`
- `is_read` (gespiegelt aus Provider)
- `is_starred` (gespiegelt)
- `provider_labels[]` / `provider_folders[]` (z.B. `INBOX`, `SENT`, `Drafts`)
- `has_attachments` (Boolean)
- `matched_contact_id` (FK, nullable)
- `matched_company_id` (FK, nullable)
- `matched_deal_id` (FK, nullable)
- `matched_project_id` (FK, nullable)
- `match_confidence` (Enum: `high | medium | low | manual | none`)
- `manual_override_at`, `manual_override_user_id` (User hat Match-Zuordnung manuell gesetzt)
- `archived_at` (Soft-Delete im HiveGrid — Provider bleibt unberührt)
**Indizes:**
- `(tenant_id, mailbox_id, received_at DESC)` — Listen-View
- `(tenant_id, matched_contact_id, received_at DESC)` — Activity-Stream am Kontakt
- `(tenant_id, matched_deal_id, received_at DESC)`
- `(tenant_id, provider_message_id)` unique
- `(tenant_id, provider_thread_id)` für Thread-Aggregation
- Trigram-Index auf `subject`, `from_address`, `body_text` für Volltext-Suche
### EmailIntegrationSyncCursor
Pro Mailbox ein Cursor für Initial-Sync und inkrementelle Pulls.
- `id`, `tenant_id`, `mailbox_id` (unique)
- `provider_history_id` (Gmail: `historyId` / Microsoft: `deltaToken`)
- `initial_sync_status` (Enum: `pending | running | completed | failed`)
- `initial_sync_progress` (Integer 0-100, nur während `running`)
- `last_cursor_advance_at`
- `error_text` (nullable)
### EmailIntegrationWebhookEvent
Roh-Log der eingegangenen Push-Events vom Provider. Append-only.
- `id`, `tenant_id`, `mailbox_id`, `received_at`
- `provider` (Enum)
- `event_payload` (JSONB — kompletter Provider-Push)
- `processing_status` (Enum: `received | processing | done | failed | discarded`)
- `processed_at`, `error_text`
- `derived_message_ids[]` (welche `EmailIntegrationMessage` aus dem Event entstanden sind)
**Retention:** 30 Tage, danach gelöscht (außer `failed` → 90 Tage für Diagnose).
### Email (HiveGrid-eigene Mails — getrennt von Mailbox-Spiegel)
Repräsentiert *eigene* Mails, die HiveGrid sendet (Booking-Bestätigungen, System-Mails, später Trigger-Mails). Nicht zu verwechseln mit EmailIntegrationMessage (gespiegelte User-Mailbox-Mails).
- `id`, `tenant_id`, `created_at`
- `purpose` (Enum: `booking_confirmation | system_notification | password_reset | invitation | acceptance_protocol | manual_outbound`)
- `from_sender_id` (FK auf TenantSendingDomain bzw. EmailSender — siehe Block C)
- `to_address`, `to_name`
- `cc_addresses[]`, `bcc_addresses[]`
- `subject`, `body_html`, `body_text`
- `delivery_status` (Enum: `queued | sending | delivered | bounced | rejected | failed`)
- `provider_message_id` (von SMTP-Provider)
- `bounce_type` (Enum: `hard | soft | null`)
- `bounce_reason` (Klartext)
- `sent_at`, `delivered_at`, `bounced_at`
- `related_contact_id`, `related_company_id`, `related_deal_id`, `related_project_id` (FKs nullable)
- `archived_at`
**Indizes:** `(tenant_id, related_contact_id, sent_at DESC)`, `(tenant_id, delivery_status, sent_at DESC)`.
### EmailRead
Tracking für *gelesen-durch-Empfänger* (transaktionale Mails von HiveGrid). Pixel-Tracking optional pro Email.
- `id`, `email_id` (FK auf Email), `tenant_id`
- `read_at`
- `reader_ip`, `reader_user_agent` (optional, DSGVO-Hinweis im Footer)
### EmailAttachment
Anhänge für sowohl `EmailIntegrationMessage` als auch `Email`.
- `id`, `tenant_id`
- `parent_kind` (Enum: `integration_message | email`)
- `parent_id`
- `filename`, `mime_type`, `size_bytes`
- `storage_path` (Scaleway-Bucket-Pfad: `tenants/{tenantId}/emails/{messageId}/{filename}`)
- `provider_attachment_id` (für Lazy-Download von Provider-Side falls Attachment nicht in Initial-Body geladen)
- `download_status` (Enum: `pending | downloaded | failed`)
### TenantSendingDomain
Verifizierte Domain, über die der Tenant *eigene* Mails versendet (transaktional + Marketing).
- `id`, `tenant_id`, `created_at`
- `domain` (z.B. `geerkens.de`)
- `dkim_public_key`, `dkim_private_key_encrypted`, `dkim_selector`
- `dkim_dns_record_text` (was der User in DNS eintragen muss)
- `spf_dns_record_text`
- `dmarc_dns_record_text`
- `verification_status` (Enum: `pending | verifying | verified | failed`)
- `verification_last_check_at`, `verification_error`
- `is_default_for_tenant` (Boolean)
- `archived_at`
**Indizes:** `(tenant_id, verification_status)`, `(domain)` global-unique.
### TenantInboundAddress
System-generierte Inbound-Adresse pro Tenant für Form-Integrationen / Email-zu-Lead.
- `id`, `tenant_id`, `created_at`
- `local_part` (z.B. `tenant-abc-leads`)
- `full_address` (z.B. `tenant-abc-leads@in.hivegrid.de`)
- `purpose` (Enum: `lead_inbox | bcc_logging | reply_routing`)
- `archived_at`
---
## Block B — Mailbox-Connect (OAuth)
### Connect-Flow Gmail
1. User in `/{tenant}/settings/integrations/email/` klickt *„Gmail verbinden"*
2. Redirect zu Google-OAuth mit Scopes: `gmail.modify`, `gmail.send`, `gmail.labels`, `userinfo.email`
3. Callback → Tokens werden encrypted gespeichert (`EmailIntegrationMailbox`)
4. System legt Pub/Sub-Subscription auf User-Mailbox an (Gmail-Watch-API)
5. Initial-Sync-Job: letzte 90 Tage Mails laden (oder konfigurierbar — Default 90)
6. `sync_status` → `active`
### Connect-Flow Microsoft (Outlook / Microsoft 365)
1. User klickt *„Outlook verbinden"*
2. Redirect zu Microsoft-OAuth mit Scopes: `Mail.ReadWrite`, `Mail.Send`, `User.Read`, `offline_access`
3. Callback → Tokens encrypted gespeichert
4. System legt Microsoft-Graph-Subscription auf `/me/messages` an (3 Tage Lebenszeit → Renewal-Job)
5. Initial-Sync analog Gmail (delta-API, letzte 90 Tage)
6. `sync_status` → `active`
### Connect-Flow für Tenant-Sending-Domain (DKIM)
1. Tenant-Admin in `/{tenant}/settings/integrations/email/sending-domain/` klickt *„Domain verbinden"*
2. Eingabe: Domain (z.B. `geerkens.de`)
3. System generiert DKIM-Schlüssel-Paar, baut DNS-TXT-Records (DKIM, SPF, DMARC)
4. UI zeigt **Klartext-Anleitung** mit Copy-to-Clipboard pro Record + Hinweis: *„Diese 3 Einträge bei deinem DNS-Anbieter (z.B. Strato, Hetzner, IONOS) anlegen. Wir prüfen automatisch alle 5 Minuten."*
5. Hintergrund-Job pollt DNS alle 5 Minuten bis Verification-Status `verified` oder Timeout 7 Tage
6. Bei `verified`: Domain ist sendebereit für transaktionale Mails (Modul 9) und Marketing-Mails (Modul 10)
### Reconnect / Token-Refresh
- Token-Refresh-Worker läuft alle 30 Min und erneuert Tokens, die in <2h ablaufen
- Bei Refresh-Fehler (User hat OAuth widerrufen) → `sync_status = revoked`, Klartext-Notification an User: *„Deine Gmail-Verbindung wurde unterbrochen — bitte erneut verbinden. [Verbindung erneuern]"*
### Disconnect
- User klickt *„Verbindung trennen"*
- Bestätigungs-Dialog mit Klartext: *„Wenn du trennst, werden keine neuen Mails mehr gespiegelt. Bisher gespiegelte Mails bleiben im CRM erhalten. Du kannst die Verbindung später wieder herstellen."*
- System ruft Provider-Token-Revoke-Endpoint auf
- `sync_status = revoked`
- Tokens werden aus DB gelöscht (encrypted, aber Defense-in-Depth)
- Webhook-Subscription beim Provider gekündigt
---
## Block C — Sending-Domain (Pflicht-Fundament für M10)
### DKIM-Setup-Anforderungen
- DKIM ist **Pflicht** für jede Sending-Domain (Marketing-Mails ohne DKIM werden von Gmail/Outlook im Spam landen)
- DKIM-Selector pro Tenant generiert (z.B. `hg-{tenant-slug}`)
- Schlüssel-Länge: 2048 Bit
- DKIM-Private-Key wird verschlüsselt gespeichert (KMS-managed-Key in Scaleway)
### SPF-Empfehlung
- Tenant erweitert seinen SPF-Record um `include:_spf.hivegrid.de`
- Falls SPF noch nicht existiert → System schlägt vollständigen Record vor
### DMARC-Empfehlung
- Empfohlen: `v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@hivegrid.de; ruf=mailto:dmarc-reports@hivegrid.de`
- Optional, nicht Pflicht für M10-Versand
### Verification-Logik
- Cron-Job alle 5 Min prüft Domains mit Status `pending` oder `verifying`
- DKIM-Check: DNS-TXT-Lookup auf `{selector}._domainkey.{domain}`
- SPF-Check: DNS-TXT-Lookup auf `{domain}` mit Pattern-Match
- Bei allen 3 OK → Status `verified`
- Bei 7 Tagen ohne Erfolg → Status `failed` + Klartext: *„Wir konnten deine DNS-Einträge nach 7 Tagen nicht finden. [Anleitung erneut anzeigen] [Support kontaktieren]"*
### Tenant ohne eigene Domain (Fallback)
- Phase 1: kein Versand möglich ohne verifizierte Sending-Domain für Marketing
- Transaktionale Mails (Booking-Confirmation, etc.) gehen über System-Domain `noreply@hivegrid.de` (mit Tenant-Branding im Klartext)
- Klartext im Marketing-Modul (M10): *„Bevor du Marketing-Mails versendest, musst du eine eigene Sending-Domain einrichten. [Domain einrichten]"*
---
## Block D — Sync-Strategie (Push statt Polling)
### Gmail Push (Pub/Sub)
- Pro Mailbox: Watch-API legt Pub/Sub-Subscription auf User-Inbox an
- Pub/Sub liefert HTTPS-Push an `/api/v1/webhooks/email/gmail`
- Push enthält nur `historyId` — kein Mail-Body
- Worker holt mit `historyId` die Diff-Liste über Gmail-API
- Pro neue Message: Body laden, in `EmailIntegrationMessage` einfügen, Auto-Match auslösen
### Microsoft Push (Graph-Subscriptions)
- Pro Mailbox: Subscription auf `/me/messages` mit Lifetime 4230 Min (~3 Tage)
- Push an `/api/v1/webhooks/email/microsoft`
- Renewal-Worker erneuert Subscription täglich
### Fallback-Polling
- Falls Webhook 4h kein Event liefert (Mailbox aktiv aber kein Push) → Worker pollt 1× pro Stunde als Sicherheitsnetz
- `last_sync_at` wird bei jedem erfolgreichen Sync (Push oder Poll) aktualisiert
### Initial-Sync
- Hintergrund-Job lädt letzte 90 Tage Mails
- Progress sichtbar in UI: *„Initial-Sync läuft — 1.234 von 5.678 Mails geladen (22%)"*
- Bei Abbruch resumefähig über `provider_history_id`-Cursor
### Klartext-Diagnose im Sync-Status (LP-10)
- `connecting`: *„Wir richten deine Mailbox-Verbindung ein, das dauert wenige Sekunden..."*
- `active`: keine Anzeige (Default-Zustand)
- `paused`: *„Sync pausiert — [Sync starten]"*
- `error`: spezifischer Fehlertext, z.B. *„Wir konnten Google nicht erreichen (HTTP 503). Wir versuchen es erneut in 5 Min. [Manuell prüfen]"*
- `revoked`: *„Deine Mailbox-Verbindung wurde widerrufen. [Erneut verbinden]"*
---
## Block E — Auto-Match-Logik
### Mail → Kontakt (über Email-Adresse)
1. Beim Eingang einer Mail: `from_address` wird gegen `ContactEmail` und `Lead.email` (in Tenant-Scope) gematcht
2. **Hard-Match (high confidence):** exakte Email-Übereinstimmung mit Contact → `matched_contact_id` gesetzt + `match_confidence = high`
3. **Hard-Match (high confidence):** Email-Übereinstimmung mit Lead → `matched_contact_id` bleibt null, aber Activity wird am Lead erzeugt
4. **No-Match:** keine Zuordnung → in Inbox sichtbar, manuell zuordbar
5. Bei *outbound* Mails: `to_addresses` werden gematcht (alle Empfänger gegen Contacts geprüft, primärer Match auf erstem Treffer)
### Mail → Deal (über Subject-Pattern)
1. Subject wird auf Patterns geprüft:
- `[Deal #123]` → Deal-ID 123 zuordnen
- `[Auftrag #456]` → Project-ID 456 zuordnen
- `[Lead #789]` → Lead-ID 789 zuordnen
2. ID muss im Tenant existieren, sonst Pattern ignoriert
3. Patterns sind Tenant-konfigurierbar in Phase 2 (Phase 1: hartcodiert)
4. Match-Confidence: `high` falls Pattern matched
### Mail → Deal (über Kontakt-Verknüpfung — Heuristik)
- Falls `matched_contact_id` gesetzt UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mit `match_confidence = medium`
- Falls Kontakt mehrere offene Deals → keine Auto-Zuordnung, manuell in UI
### Manuelle Zuordnung
- Im Mail-Detail-View: User kann manuell *„Zu Kontakt zuordnen"* / *„Zu Deal zuordnen"* / *„Zu Projekt zuordnen"*
- `manual_override_at` + `manual_override_user_id` werden gesetzt
- Manuelle Zuordnung überschreibt Auto-Match
- Auto-Match-Logik versucht **nicht erneut** zu matchen, falls `manual_override_at` gesetzt
### Edge-Cases
- **Mehrere Contacts mit gleicher Email** (z.B. private + geschäftliche Adresse identisch): primärer Contact (mit `is_primary` Email) wird gewählt; UI-Hinweis: *„Diese Email gehört zu mehreren Kontakten. Aktuell zugeordnet: [Name]. [Anders zuordnen]"*
- **Eigene Mails an eigene Mailbox** (User schreibt sich selbst): `direction = outbound`, kein Auto-Match auf Contact (eigene Email-Adresse ist in `EmailIntegrationMailbox` registriert und wird ausgeschlossen)
- **Newsletter / Bulk-Sender** (List-Unsubscribe-Header vorhanden): keine Auto-Verknüpfung mit Contact, Mail wird in Inbox als *„Newsletter / Bulk"* gekennzeichnet
---
## Block F — Inbox-View
### Liste (`/{tenant}/emails`)
**Zu zeigende Daten pro Eintrag:**
- Absender (Name + Email)
- Betreff
- Snippet (erste 100 Zeichen Body)
- Empfangsdatum (relativ, < 7 Tage; absolut sonst)
- Verknüpfter Kontakt / Deal / Projekt (falls gemacht)
- Read/Unread-Indikator
- Anhang-Indikator (falls vorhanden)
- Mailbox-Indikator (falls User mehrere Mailboxen hat)
**Benötigte UI-Elemente:**
- Tabellarische oder Listen-Anzeige
- Such-Funktion (Volltext über Subject + Body + Absender)
- Filter:
- Mailbox (Multi-Select, wenn User mehrere hat)
- Direction (`inbound | outbound | all`)
- Read-Status (`gelesen | ungelesen | alle`)
- Verknüpft-mit (`Kontakt | Deal | Projekt | nicht verknüpft`)
- Datum (Date-Range-Picker)
- Anhang (Boolean)
- Bulk-Auswahl + Bulk-Actions (Read/Unread markieren, Archivieren)
- Pagination (Cursor-basiert, 50 pro Page)
- Toggle „Archivierte anzeigen"
**Operationen:**
- Klick auf Zeile → Detail-View
- Bulk-Read-/Unread-Markierung (sync zurück zum Provider)
- Bulk-Archive im HiveGrid (Provider unangetastet)
**Performance:**
- Index `(tenant_id, mailbox_id, received_at DESC)`
- Trigram-Index für Volltext-Suche
- Permissions-Filter: `email.read_own` zeigt nur eigene Mailboxen, `email.read_all` zeigt alle Tenant-Mailboxen
### Detail (`/{tenant}/emails/:id`)
**Zu zeigende Daten:**
- Vollständige Mail (From, To, CC, Subject, Body-HTML)
- Empfangsdatum + Mailbox
- Anhänge (Liste mit Download-Link)
- Verknüpfter Kontakt / Deal / Projekt (klickbar zu Detail-View)
- Match-Confidence + Hinweis: *„Auto-erkannt"* / *„Manuell zugeordnet von [User]"*
- Thread-Anzeige (alle Mails mit gleichem `provider_thread_id`, chronologisch)
**Benötigte UI-Elemente:**
- Mail-Body-Render (HTML mit Content-Security-Policy: keine externen Scripts, externe Bilder hinter „Bilder anzeigen"-Toggle)
- Attachment-Liste mit Download
- Thread-Aggregat (collapsed/expanded)
- Reply / Reply-All / Forward-Funktionen (öffnet Compose mit Pre-Fill)
- Verknüpfungs-Editor (Kontakt / Deal / Projekt zuordnen oder ändern)
- Read/Unread-Toggle
- Archivieren-Funktion
**Operationen:**
- Reply / Reply-All / Forward
- Verknüpfungen ändern (manuelle Override)
- Anhang downloaden
- Mail im Provider öffnen (Deep-Link zu Gmail/Outlook-Web)
- Archivieren
**Klartext-Hinweise:**
- Externe Bilder geblockt: *„Externe Bilder geladen? [Anzeigen]"*
- Mail nicht zugeordnet: *„Diese Mail ist keinem Kontakt zugeordnet. [Zu Kontakt zuordnen] [Neuen Kontakt anlegen]"*
---
## Block G — Outbound-Compose
### Compose-Funktion
**Aufruf:**
- Aus Kontakt-Detail: *„Email schreiben"* → Empfänger vorausgefüllt mit Primary-Email
- Aus Deal-Detail: *„Email schreiben"* → Empfänger = primärer Kontakt am Deal, Subject pre-fill `[Deal #123] `
- Aus Projekt-Detail: analog mit `[Auftrag #456] `
- Aus Inbox-Detail (Reply/Forward): Empfänger und Subject vorgegeben
- Standalone aus `/{tenant}/emails/new`: leerer Compose
**Benötigte UI-Elemente:**
- Empfänger-Felder (To, CC, BCC) mit Auto-Complete aus Contacts
- Subject-Feld
- Body-Editor (Rich-Text — Bold/Italic/Link/Liste/Bilder/Inline-Attachments)
- Anhang-Upload (max. 25 MB pro Mail Provider-Limit)
- Mailbox-Auswahl (falls User mehrere Mailboxen hat — Default: Default-Mailbox des Users)
- Send-Funktion + Save-as-Draft-Funktion
- Schedule-Send (Phase 2)
**Send-Pfad:**
- Mail wird über die verbundene User-Mailbox gesendet (Gmail-API `messages.send` / Microsoft-Graph `sendMail`)
- Provider-Side erscheint die Mail im *Sent*-Folder des Users (nativ)
- HiveGrid spiegelt die gesendete Mail nach erfolgreichem Send als `EmailIntegrationMessage` mit `direction = outbound`
- Activity-Stream-Eintrag wird erzeugt
**Klartext-Fehler:**
- Mailbox nicht verbunden: *„Du hast keine Mailbox verbunden. [Mailbox verbinden]"*
- Send-Fehler: *„Mail konnte nicht gesendet werden — Google meldet 'Quote exceeded'. In 1h erneut versuchen oder anderen Account verwenden. [Erneut versuchen]"*
- Empfänger ohne Email: *„Der Kontakt hat keine Email-Adresse hinterlegt. [Email ergänzen]"*
**BCC-Logging-Adresse:**
- Optional: User kann in Settings aktivieren *„Beim Senden BCC an `tenant-{tenantId}-log@in.hivegrid.de`"*
- Für Edge-Case: User schreibt Mail aus nativem Gmail-Client, möchte trotzdem im CRM loggen → BCC-Adresse erzeugt automatisch eine `EmailIntegrationMessage`-Entry mit Auto-Match
---
## Block H — Activity-Stream-Integration
### Activity-Typen die M9 produziert
- `email_received` — eingehende Mail mit gemachtem Match
- `email_sent` — ausgehende Mail
- `email_unmatched` (Phase 2 — falls UX zeigt: „neue ungeordnete Mail")
- `email_match_changed` — Audit-Event bei manuellem Override
### Verknüpfungen
- Activity erscheint im Stream der gematchten Entity (Contact / Deal / Project / Lead)
- `summary_text` Beispiel: *„Eingehende Mail von Max Mustermann: ‚Anfrage Wartung'"*
- `metadata` enthält: Mailbox-ID, Provider-Message-ID, Subject, Snippet
- Klick auf Activity → öffnet Mail-Detail-View
### Permission-Wirkung
- Activity sichtbar nur für User mit `email.read_own` (eigene Mailboxen) bzw. `email.read_all`
- Falls User keine Email-Permissions hat: Activity zeigt nur *„Email-Aktivität (nicht einsehbar)"* ohne Details
---
## Block I — Permissions
### Permission-IDs
| Permission | Erlaubt |
|---|---|
| `email.read_own` | Eigene verbundene Mailbox-Mails sehen |
| `email.read_all` | Alle Tenant-Mailbox-Mails sehen |
| `email.write` | Mails verfassen + senden über eigene Mailbox |
| `email.admin` | Sending-Domain einrichten, Inbound-Adressen verwalten, fremde Mailbox-Connections trennen |
### Bundle-Mapping
| Bundle | Atomare Permissions |
|---|---|
| `email.none` | (keine) |
| `email.read_own` | `email.read_own` + `email.write` (eigene Mailbox schreiben können ist Standard) |
| `email.read_all` | `email.read_own` + `email.read_all` + `email.write` |
| `email.admin` | alle obigen + `email.admin` |
### Anwendung in Routes
- `/{tenant}/emails` → `email.read_own` oder `email.read_all`
- `/{tenant}/emails/:id` → analog (mit Owner-Check bei `read_own`: nur Mails aus Mailbox des Users)
- `/{tenant}/emails/new` (Compose) → `email.write` + verbundene Mailbox
- `/{tenant}/settings/integrations/email/` → jeder eingeloggte User für eigene Mailbox; Sending-Domain nur `email.admin` oder `tenant.admin`
### Owner-Check bei `read_own`
- User mit `email.read_own` sieht nur Mails aus Mailboxen, deren `owner_user_id = self`
- Auto-Match-Logik bleibt aktiv über alle Mailboxen, aber Anzeige im Activity-Stream eines Kontakts wird permissioned: User mit nur `email.read_own` sieht nur Mails aus seinen Mailboxen am Kontakt
---
## Block J — Provider-Adapter (LP-11)
### EmailProviderInterface
Gemeinsames Interface für Gmail- und Microsoft-Adapter:
- `connect(authCode) → MailboxConnection`
- `disconnect(mailboxId) → void`
- `fetchMessages(cursor, limit) → MessageBatch`
- `getMessage(providerMessageId) → MessageDetail`
- `sendMessage(MessageDraft) → ProviderMessageId`
- `subscribeToWebhook(mailboxId) → SubscriptionInfo`
- `renewWebhook(subscriptionId) → SubscriptionInfo`
- `revokeWebhook(subscriptionId) → void`
- `markRead(providerMessageId, isRead) → void`
- `downloadAttachment(providerMessageId, attachmentId) → Stream`
### Implementierungen
- **GmailAdapter:** spricht Gmail-API + Pub/Sub
- **MicrosoftAdapter:** spricht Microsoft-Graph + Subscription-API
### Klartext-Diagnose pro Adapter (LP-10)
Adapter liefern Provider-Fehler übersetzt:
- Gmail `403 quota exceeded` → *„Du hast das tägliche Sende-Limit erreicht. Es wird in [X Stunden] zurückgesetzt."*
- Microsoft `401 token expired` → *„Outlook-Verbindung abgelaufen — bitte erneut verbinden."*
- Generisch unbekannter Fehler → *„Es gab ein Problem mit deiner Mailbox-Verbindung. Wir versuchen es automatisch in 5 Min erneut. [Logs anzeigen]"* (Logs-Anzeige Permission-gegated über `email.admin`)
---
## Block K — Phase 2 / spätere Features
- Erweiterte Filter (gespeicherte Filter, Smart-Folders)
- Bulk-Operations: Multi-Reply, Multi-Forward
- Email-Templates für Outbound (Quick-Reply-Snippets)
- Mail-Merge in Compose (Personalisierung pro Empfänger)
- Schedule-Send (Mail um Datum X versenden)
- Tracking-Pixel für Outbound (Open-Tracking — Phase 2 für transaktionale Mails, in M10 schon Phase 1)
- Snooze-Funktion (Mail kommt in 3 Tagen wieder in Inbox)
- Auto-Forwarding-Regeln (alle Mails von `@geerkens.de` an Sales-Team weiterleiten)
- Custom-Subject-Patterns für Auto-Match (Tenant-konfigurierbar)
- Shared-Inbox (mehrere User auf 1 Mailbox, mit Assignment)
---
## Architektur-Vorschriften (Querschnitt)
- **LP-9:** Requirements-pur, kein Layout
- **LP-10, AV #1:** Klartext-Diagnose bei jedem Sync-Fehler, jeder OAuth-Disconnect, jedem Send-Fehler
- **LP-11:** Provider-Adapter-Pattern, Gmail + Microsoft als erste Implementierungen
- **LP-13:** Mail-Bodies werden in Scaleway-DB gehalten, Attachments in Scaleway-Storage (EU)
- **AV #5 Permissions-aware-Default:** Inbox-Liste filtert automatisch nach `email.read_own` vs. `read_all`
- **AV #6 Audit-Trail:** Manueller Match-Override loggt `audit_event`
---
## Detail-Spec-Status: DRAFT
Erste vollständige Detail-Spec für Modul 9. **Vor Bau:** Validierung der Provider-Webhook-Lifecycle (insbes. Microsoft-3-Tage-Renewal), DKIM-DNS-Check-Implementierung mit echter Domain testen.
**Offene Detail-Punkte (nicht-blockierend):**
- Konkretes Encryption-KMS-Setup für OAuth-Tokens (Implementierungs-Detail)
- Konkrete Quotas pro Provider (Gmail: 1 Mrd Quota-Units/Tag — reicht weit; Microsoft: 10.000 Mails/Tag pro Mailbox)
- Initial-Sync-Default-Tiefe (90 Tage vorgeschlagen, ggf. Tenant-konfigurierbar)
- Subframe-UI-Designs (separat)
- Verknüpfung mit Modul 24 Globale Suche (Mail-Volltext indexieren)