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

24 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
9 Email Inbox + Sync (Gmail/Outlook) 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-7
LP-9
LP-10
LP-11
LP-13
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)