24 KiB
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 |
|
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_atowner_user_id(FK auf TenantUser — wem gehört die Mailbox)provider(Enum:gmail | microsoft)email_address(unique pro Tenant)display_nameoauth_access_token_encrypted,oauth_refresh_token_encrypted,oauth_token_expires_atoauth_scope_granted(Liste der gewährten Scopes)sync_status(Enum:connecting | active | paused | error | revoked)last_sync_at,last_error_textwebhook_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_atprovider_message_id(Gmail-id/ Microsoft-internetMessageId) — unique pro Mailboxprovider_thread_id(Gmail-threadId/ Microsoft-conversationId)direction(Enum:inbound | outbound)from_address,from_nameto_addresses[],cc_addresses[],bcc_addresses[]subjectbody_html,body_textreceived_at,sent_atis_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_textfü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ährendrunning)last_cursor_advance_aterror_text(nullable)
EmailIntegrationWebhookEvent
Roh-Log der eingegangenen Push-Events vom Provider. Append-only.
id,tenant_id,mailbox_id,received_atprovider(Enum)event_payload(JSONB — kompletter Provider-Push)processing_status(Enum:received | processing | done | failed | discarded)processed_at,error_textderived_message_ids[](welcheEmailIntegrationMessageaus 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_atpurpose(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_namecc_addresses[],bcc_addresses[]subject,body_html,body_textdelivery_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_atrelated_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_idread_atreader_ip,reader_user_agent(optional, DSGVO-Hinweis im Footer)
EmailAttachment
Anhänge für sowohl EmailIntegrationMessage als auch Email.
id,tenant_idparent_kind(Enum:integration_message | email)parent_idfilename,mime_type,size_bytesstorage_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_atdomain(z.B.geerkens.de)dkim_public_key,dkim_private_key_encrypted,dkim_selectordkim_dns_record_text(was der User in DNS eintragen muss)spf_dns_record_textdmarc_dns_record_textverification_status(Enum:pending | verifying | verified | failed)verification_last_check_at,verification_erroris_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_atlocal_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
- User in
/{tenant}/settings/integrations/email/klickt „Gmail verbinden" - Redirect zu Google-OAuth mit Scopes:
gmail.modify,gmail.send,gmail.labels,userinfo.email - Callback → Tokens werden encrypted gespeichert (
EmailIntegrationMailbox) - System legt Pub/Sub-Subscription auf User-Mailbox an (Gmail-Watch-API)
- Initial-Sync-Job: letzte 90 Tage Mails laden (oder konfigurierbar — Default 90)
sync_status→active
Connect-Flow Microsoft (Outlook / Microsoft 365)
- User klickt „Outlook verbinden"
- Redirect zu Microsoft-OAuth mit Scopes:
Mail.ReadWrite,Mail.Send,User.Read,offline_access - Callback → Tokens encrypted gespeichert
- System legt Microsoft-Graph-Subscription auf
/me/messagesan (3 Tage Lebenszeit → Renewal-Job) - Initial-Sync analog Gmail (delta-API, letzte 90 Tage)
sync_status→active
Connect-Flow für Tenant-Sending-Domain (DKIM)
- Tenant-Admin in
/{tenant}/settings/integrations/email/sending-domain/klickt „Domain verbinden" - Eingabe: Domain (z.B.
geerkens.de) - System generiert DKIM-Schlüssel-Paar, baut DNS-TXT-Records (DKIM, SPF, DMARC)
- 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."
- Hintergrund-Job pollt DNS alle 5 Minuten bis Verification-Status
verifiedoder Timeout 7 Tage - 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
pendingoderverifying - 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
historyIddie Diff-Liste über Gmail-API - Pro neue Message: Body laden, in
EmailIntegrationMessageeinfügen, Auto-Match auslösen
Microsoft Push (Graph-Subscriptions)
- Pro Mailbox: Subscription auf
/me/messagesmit 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_atwird 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)
- Beim Eingang einer Mail:
from_addresswird gegenContactEmailundLead.email(in Tenant-Scope) gematcht - Hard-Match (high confidence): exakte Email-Übereinstimmung mit Contact →
matched_contact_idgesetzt +match_confidence = high - Hard-Match (high confidence): Email-Übereinstimmung mit Lead →
matched_contact_idbleibt null, aber Activity wird am Lead erzeugt - No-Match: keine Zuordnung → in Inbox sichtbar, manuell zuordbar
- Bei outbound Mails:
to_addresseswerden gematcht (alle Empfänger gegen Contacts geprüft, primärer Match auf erstem Treffer)
Mail → Deal (über Subject-Pattern)
- Subject wird auf Patterns geprüft:
[Deal #123]→ Deal-ID 123 zuordnen[Auftrag #456]→ Project-ID 456 zuordnen[Lead #789]→ Lead-ID 789 zuordnen
- ID muss im Tenant existieren, sonst Pattern ignoriert
- Patterns sind Tenant-konfigurierbar in Phase 2 (Phase 1: hartcodiert)
- Match-Confidence:
highfalls Pattern matched
Mail → Deal (über Kontakt-Verknüpfung — Heuristik)
- Falls
matched_contact_idgesetzt UND der Kontakt hat genau 1 offenen Deal → Deal automatisch zuordnen mitmatch_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_idwerden gesetzt- Manuelle Zuordnung überschreibt Auto-Match
- Auto-Match-Logik versucht nicht erneut zu matchen, falls
manual_override_atgesetzt
Edge-Cases
- Mehrere Contacts mit gleicher Email (z.B. private + geschäftliche Adresse identisch): primärer Contact (mit
is_primaryEmail) 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 inEmailIntegrationMailboxregistriert 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_ownzeigt nur eigene Mailboxen,email.read_allzeigt 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-GraphsendMail) - Provider-Side erscheint die Mail im Sent-Folder des Users (nativ)
- HiveGrid spiegelt die gesendete Mail nach erfolgreichem Send als
EmailIntegrationMessagemitdirection = 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 Matchemail_sent— ausgehende Mailemail_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_textBeispiel: „Eingehende Mail von Max Mustermann: ‚Anfrage Wartung'"metadataenthä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_ownoderemail.read_all/{tenant}/emails/:id→ analog (mit Owner-Check beiread_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 nuremail.adminodertenant.admin
Owner-Check bei read_own
- User mit
email.read_ownsieht nur Mails aus Mailboxen, derenowner_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_ownsieht nur Mails aus seinen Mailboxen am Kontakt
Block J — Provider-Adapter (LP-11)
EmailProviderInterface
Gemeinsames Interface für Gmail- und Microsoft-Adapter:
connect(authCode) → MailboxConnectiondisconnect(mailboxId) → voidfetchMessages(cursor, limit) → MessageBatchgetMessage(providerMessageId) → MessageDetailsendMessage(MessageDraft) → ProviderMessageIdsubscribeToWebhook(mailboxId) → SubscriptionInforenewWebhook(subscriptionId) → SubscriptionInforevokeWebhook(subscriptionId) → voidmarkRead(providerMessageId, isRead) → voiddownloadAttachment(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.dean 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_ownvs.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)