Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M10-email-marketing.md
T

27 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
10 Email-Marketing 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-4
LP-7
LP-9
LP-10
LP-11
LP-13
requirements-pur

Modul 10 — Email-Marketing

Detail-Spec gemäß LP-9. Phase-1-Voll-Modul (User-Korrektur — kritisch genug für Geerkens-Launch). Löst HubSpot-Marketing-Hub ab (LP-7). Versendet Kampagnen an CRM-Segmente, trackt Opens/Clicks, integriert sich in Automation-Engine (M17) als Action send-marketing-email. Setzt verifizierte Sending-Domain aus M9 voraus.

Themenblöcke

A. Datenmodell
B. Menü-Struktur und Routes
C. Kampagnen-Builder
D. Empfänger-Listen (CRM-Segmente)
E. Versand-Logik (sofort + zeitgesteuert)
F. Open-/Click-Tracking
G. Bounce-Handling
H. Unsubscribe & DSGVO
I. Templates & Sender
J. Trigger-Mails (über Automation-Engine)
K. Anti-Spam-Schutz
L. Permissions
M. Phase 2

Block A — Datenmodell

Campaign

Tenant-scoped (RLS).

  • id, tenant_id, created_at, updated_at, created_by_user_id
  • name (interner Name)
  • subject (Email-Betreff)
  • preheader (Vorschau-Text in Inbox)
  • template_id (FK auf EmailTemplate, optional — falls aus Template gestartet)
  • body_html, body_text (Mailrender)
  • sender_id (FK auf EmailSender)
  • recipient_segment_id (FK auf RecipientSegment)
  • recipient_list_snapshot (JSONB — eingefrorene Empfänger-IDs zum Versand-Zeitpunkt)
  • status (Enum: draft | scheduled | sending | sent | paused | failed | cancelled)
  • scheduled_at (nullable — bei scheduled-Status gesetzt)
  • sending_started_at, sending_finished_at
  • total_recipients (Integer)
  • delivered_count, bounced_count, opened_count, clicked_count, unsubscribed_count, complaint_count
  • archived_at

Indizes: (tenant_id, status, scheduled_at), (tenant_id, created_at DESC).

OutboundEmail

Pro Empfänger pro Kampagne ein Eintrag (Tracking-Granularität).

  • id, tenant_id, campaign_id, created_at
  • recipient_contact_id (FK auf Contact)
  • recipient_email (Snapshot zum Versand-Zeitpunkt — falls Email später geändert)
  • recipient_first_name, recipient_last_name (Snapshot — für Personalisierung)
  • personalization_payload (JSONB — alle vorgemerkten Personalisierungs-Werte)
  • delivery_status (Enum: queued | sending | delivered | bounced_hard | bounced_soft | complained | rejected | suppressed | failed)
  • provider_message_id (von SMTP-Provider)
  • bounce_type, bounce_reason_text
  • sent_at, delivered_at, bounced_at
  • tracking_token (kryptographischer 32-Zeichen-Token für Open/Click-URLs)
  • unsubscribe_token (separat, 32 Zeichen — verlinkt zu Unsubscribe-Page)

Indizes: (tenant_id, campaign_id, delivery_status), (tenant_id, recipient_contact_id, sent_at DESC), (tracking_token) unique, (unsubscribe_token) unique.

OutboundEmailOpen

Tracking-Pixel-Hits.

  • id, outbound_email_id, tenant_id, opened_at
  • reader_ip (anonymisiert nach 30 Tagen — letzte Oktett geNULLt)
  • reader_user_agent
  • is_first_open (Boolean — erstes Open pro outbound_email_id)

Indizes: (outbound_email_id, opened_at), (tenant_id, opened_at DESC) für Aggregat-Stats.

OutboundEmailClick

  • id, outbound_email_id, tenant_id, clicked_at
  • link_url (welche URL wurde geklickt)
  • link_label (sichtbarer Link-Text — falls verfügbar)
  • reader_ip (anonymisiert), reader_user_agent

Indizes: (outbound_email_id, clicked_at), (tenant_id, link_url) für Click-Map.

EmailTemplate

Wiederverwendbare Vorlagen für Kampagnen.

  • id, tenant_id, created_at, updated_at, created_by_user_id
  • name, description
  • subject_default, preheader_default
  • body_html, body_text
  • is_template_origin (kam aus Branchen-Template?)
  • archived_at

EmailSender

Versand-Identität (Name + From-Email + Sending-Domain).

  • id, tenant_id, created_at
  • from_name (z.B. „Geerkens GmbH")
  • from_email (z.B. marketing@geerkens.de)
  • reply_to_email (optional)
  • sending_domain_id (FK auf TenantSendingDomain aus M9 — Pflicht-Verknüpfung)
  • is_default (Boolean — Default-Sender für neue Kampagnen)
  • archived_at

Constraint: from_email-Domain muss zu sending_domain_id.domain passen (sonst DKIM-Fail).

Unsubscribe

Pro Contact + Tenant, dauerhaft.

  • id, tenant_id, contact_id (FK)
  • email_address (Snapshot — falls Contact gelöscht wird, bleibt Adresse blockiert)
  • scope (Enum: all_marketing | specific_campaign_type | global)
  • specific_campaign_type (nullable — z.B. newsletter | promotion | service_announcement, Phase 2)
  • unsubscribed_at
  • unsubscribed_via (Enum: link_click | manual_admin | bounce_auto | complaint_auto)
  • unsubscribe_reason (optional Freitext aus Unsubscribe-Page)

Indizes: (tenant_id, email_address) unique pro Tenant für all_marketing-Scope.

RecipientSegment

Definition einer Empfänger-Liste basierend auf CRM-Filter-Kriterien.

  • id, tenant_id, created_at, updated_at, created_by_user_id
  • name, description
  • entity_type (Enum: contact | lead — Phase 1 nur Contact)
  • filter_definition (JSONB — Filter-Tree analog zu CRM-Listen-Filter, siehe Block D)
  • is_static_snapshot (Boolean — falls true: Empfänger einmalig eingefroren, sonst dynamisch live ausgewertet)
  • static_recipient_ids[] (nur bei is_static_snapshot=true)
  • archived_at

EmailSuppressionList

Globale Tenant-Liste von blockierten Adressen (Hard-Bounces, Complaints, manuell).

  • id, tenant_id, email_address, created_at
  • reason (Enum: hard_bounce | complaint | manual_admin | invalid_format)
  • reason_detail (Klartext)
  • added_by_user_id (nullable — System bei Auto-Add)

Indizes: (tenant_id, email_address) unique.


Block B — Menü-Struktur und Routes

Sidebar-Hauptpunkt: Email-Marketing.

Routen:

/{tenant}/email-marketing                        → Übersicht (Dashboard)
/{tenant}/email-marketing/campaigns              → Kampagnen-Liste
/{tenant}/email-marketing/campaigns/new          → Neue Kampagne
/{tenant}/email-marketing/campaigns/:id          → Kampagnen-Detail (Stats + Edit)
/{tenant}/email-marketing/campaigns/:id/edit     → Kampagnen-Editor
/{tenant}/email-marketing/templates              → Template-Liste
/{tenant}/email-marketing/templates/new          → Neues Template
/{tenant}/email-marketing/templates/:id          → Template-Detail
/{tenant}/email-marketing/senders                → Sender-Verwaltung
/{tenant}/email-marketing/segments               → Empfänger-Segmente
/{tenant}/email-marketing/segments/:id           → Segment-Detail (Vorschau Empfänger)
/{tenant}/email-marketing/suppressions           → Suppression-Liste

/unsubscribe/{token}                             → Öffentliche Unsubscribe-Page (kein Login nötig)
/track/open/{token}                              → Tracking-Pixel (1x1-PNG)
/track/click/{token}/?url=...                    → Click-Tracking-Redirect

Block C — Kampagnen-Builder

Kampagne anlegen — Schritte

Schritt 1 — Basis:

  • Name (intern)
  • Sender wählen (Default: Tenant-Default-Sender)
  • Subject + Preheader
  • Optional: Template als Ausgangspunkt

Schritt 2 — Inhalt:

  • Body-Editor (Rich-Text mit HTML-Quelltext-Toggle)
  • Personalisierungs-Tokens: {{first_name}}, {{last_name}}, {{company_name}}, Custom-Felder via {{custom.heizungsanlage_modell}}
  • Bilder-Upload mit automatischer Hosting-URL (Scaleway-Bucket)
  • Footer-Bereich mit Pflicht-Inhalt: Absender-Adresse (DSGVO-Impressum), Unsubscribe-Link (auto-injiziert wenn nicht vorhanden)
  • Vorschau-Funktion: Browser-Render in Desktop + Mobile-Breite

Schritt 3 — Empfänger:

  • Segment wählen (existierendes RecipientSegment) ODER ad-hoc-Filter bauen
  • Vorschau mit Anzahl auflösbarer Empfänger
  • Auto-Exclusion-Anzeige: „X aus Y Empfängern werden ausgeschlossen (Unsubscribe / Hard-Bounce / Suppression)"

Schritt 4 — Test-Versand:

  • „Test-Mail senden" → an User-eigene Email-Adresse (oder freie Eingabe von max. 5 Test-Adressen)
  • Test-Mail nutzt selben Render-Pfad, aber zählt nicht zu Stats
  • Personalisierung-Tokens werden mit Sample-Daten gefüllt (z.B. {{first_name}} → „Max")

Schritt 5 — Versand-Zeitpunkt:

  • Sofort versenden (nach Bestätigungs-Modal)
  • Geplanter Versand (Date-Time-Picker, mind. 5 Min in Zukunft, Tenant-Timezone-aware)
  • Als Entwurf speichern (kein Versand)

Schritt 6 — Bestätigung:

  • Übersicht aller Daten
  • Klartext: „Du bist im Begriff, an [X] Empfänger eine Marketing-Mail zu versenden. Pflicht-Checks: Sender-Domain verifiziert ✓, Unsubscribe-Link enthalten ✓, Impressum enthalten ✓. [Versenden]"
  • Bei nicht erfüllten Checks → Block + Klartext mit Fix-Link

Pflicht-Validierungen vor Versand

  • Sender hat verifizierte Sending-Domain (DKIM aus M9 grün)
  • Body enthält Unsubscribe-Token-Link (sonst auto-injiziert in Footer)
  • Body enthält physische Absender-Adresse (DSGVO-Impressum — Hinweis falls nicht erkannt)
  • Subject nicht leer
  • Empfänger-Liste > 0 Empfänger nach Auto-Exclusion
  • Tenant-Daily-Cap nicht überschritten (siehe Block K)

Block D — Empfänger-Listen (CRM-Segmente)

Filter-Engine

Filter analog zu CRM-Listen-Filter (Modul 1):

  • Tags (AND/OR)
  • lifecycle_stage (Custom-Feld — falls Tenant das Konzept verwendet)
  • Custom-Felder (Werte-Filter pro CustomFieldDefinition)
  • Verantwortlicher
  • Erstellt-Datum-Range
  • Verknüpft mit aktivem Deal (Boolean)
  • Letzte Activity (Datum-Range)
  • is_endkunde Boolean
  • Sprache (DE / EN — für i18n-Kampagnen)

Filter-Tree

JSONB-Struktur unterstützt verschachtelte AND/OR-Bäume:

{
  "operator": "AND",
  "conditions": [
    {"field": "tag", "op": "contains", "value": "newsletter"},
    {
      "operator": "OR",
      "conditions": [
        {"field": "custom.wartungsvertrag", "op": "eq", "value": true},
        {"field": "lifecycle_stage", "op": "eq", "value": "kunde"}
      ]
    }
  ]
}

Auto-Exclusion (immer angewendet)

Beim Auflösen eines Segments für Versand werden automatisch ausgeschlossen:

  • Contacts in Unsubscribe mit Scope all_marketing oder global
  • Email-Adressen in EmailSuppressionList
  • Contacts ohne Email-Adresse
  • Contacts mit archived_at gesetzt
  • Contacts ohne dokumentiertes Opt-In (siehe Block H)

Static vs. Dynamic Segments

  • Dynamic (Default): beim Versand wird Filter live ausgewertet → aktuelle Empfänger
  • Static Snapshot: Liste wird beim Anlegen eingefroren → Versand an exakt diese IDs
  • Use-Case Static: einmaliger Versand an genau definierte Liste, die sich später ändert

Segment-Detail-View

Zu zeigende Daten:

  • Filter-Definition (lesbar darstellt)
  • Aktuelle Empfänger-Anzahl (live)
  • Aufgeschlüsselt: Total / nach Auto-Exclusion versendbar / pro Auto-Exclusion-Grund
  • Empfänger-Vorschau (max. 50 Sample-Contacts)

Operationen:

  • Filter editieren
  • Als Static Snapshot konvertieren
  • Duplizieren
  • Archivieren

Block E — Versand-Logik

Sofort-Versand

  1. Bei Versenden-Klick: Campaign.status = sending, recipient_list_snapshot einfrieren
  2. Worker erzeugt OutboundEmail pro Empfänger (Batch von 1.000)
  3. Worker dispatched in Send-Queue (BullMQ)
  4. Send-Worker spricht SMTP-Provider (Phase 1: Scaleway TEM oder analoger EU-Provider mit DKIM)
  5. Pro Mail: Personalisierungs-Render, DKIM-Sign, Send
  6. Bei Send-Erfolg: delivery_status = sending (wird dann durch Provider-Webhook auf delivered / bounced geupdated)
  7. Bei Send-Fehler: Retry max. 3× mit exponentiellem Backoff
  8. Nach allen Sends: Campaign.status = sent

Geplanter Versand

  1. Bei Geplant: Campaign.status = scheduled, scheduled_at gesetzt
  2. Cron-Job (alle 1 Min) prüft: WHERE status = scheduled AND scheduled_at <= NOW() → triggert Sofort-Versand-Pfad
  3. User kann bis 5 Min vor scheduled_at noch Pausieren / Cancellen → status = paused | cancelled
  4. paused kann re-aktiviert werden, cancelled ist final

Throttling

  • Pro Tenant: max. 100 Mails/Min (Provider-Schutz, kann bei Bedarf erhöht werden)
  • Pro Empfänger-Domain: max. 30 Mails/Min (Schutz vor Gmail-/Outlook-Rate-Limits)

Klartext-Hinweise

  • Versand läuft: „Kampagne wird versendet — 1.234 von 5.678 Mails verschickt (22%, geschätzt fertig in 8 Min)"
  • Versand pausiert: „Versand pausiert. [Fortsetzen] [Abbrechen]"
  • Versand fehlgeschlagen: „Versand fehlgeschlagen — Sender-Domain wurde widerrufen. Domain neu verifizieren und erneut starten. [Domain prüfen]"

Block F — Open-/Click-Tracking

Open-Tracking

  • Im Body wird vor </body> ein 1×1-PNG <img> injiziert mit URL /track/open/{tracking_token}
  • Tracking-Endpoint:
    • Loggt OutboundEmailOpen-Eintrag
    • Erstes Open setzt is_first_open = true
    • Mehrfach-Opens werden alle geloggt (für Re-Engagement-Stats)
    • Liefert echtes 1×1-PNG zurück (Cache-Headers no-store)
  • DSGVO-Hinweis im Footer der Kampagne: „Diese Mail enthält einen Tracking-Pixel. [Mehr Info]"

Click-Tracking

  • Bei Render: alle <a href="..."> werden umgeschrieben auf /track/click/{tracking_token}/?url={original_encoded}
  • Tracking-Endpoint:
    • Loggt OutboundEmailClick-Eintrag
    • 302-Redirect zur Original-URL
  • Ausnahmen: mailto:, tel:, Unsubscribe-Link (eigener Endpoint)

Stats-Aggregation

Kampagnen-Detail-View zeigt:

  • Versendet: X
  • Zugestellt: X (Y%)
  • Hard-Bounces: X (Y%)
  • Soft-Bounces: X (Y%)
  • Geöffnet: X (Y% — Unique-Open-Rate, Sekunde-Open zählt nicht)
  • Geklickt: X (Y% — Unique-Click-Rate)
  • Click-through-Rate (Geklickt / Geöffnet)
  • Abgemeldet: X (Y%)
  • Beschwerden: X (Y% — über ISP-Feedback-Loops)

Pro-Empfänger-Anzeige:

  • Tabellarische Liste aller OutboundEmail einer Kampagne
  • Spalten: Empfänger, Status, Zugestellt-Zeit, Geöffnet-Zeit, Geklickt-Zeit
  • Filter nach Status
  • Klick auf Eintrag → Aktivitäts-Detail (alle Opens und Clicks chronologisch)

Click-Map:

  • Welche URLs wie oft geklickt
  • Sortiert absteigend nach Klicks

Block G — Bounce-Handling

Bounce-Klassifikation

Hard-Bounce (permanent):

  • Adresse existiert nicht (5.1.1)
  • Domain existiert nicht (5.1.2)
  • Mailbox blockiert HiveGrid (5.7.1)

→ Auto-Add zu EmailSuppressionList mit reason = hard_bounce → Contact.email_invalid_at gesetzt (UI zeigt Warnung in Kontakt-Detail) → Künftige Marketing-Versendungen blockiert → Activity am Kontakt: „Email-Adresse ungültig — Hard-Bounce am [Datum]"

Soft-Bounce (temporär):

  • Mailbox voll (4.2.2)
  • Server temporär down (4.x.x)
  • Greylisting

→ Retry max. 3× über 24h → Nach 3 Fehlversuchen wie Hard-Bounce behandeln (Soft-to-Hard-Conversion) → Activity am Kontakt: „Email konnte nach 3 Versuchen nicht zugestellt werden"

Complaint (Spam-Beschwerde):

  • ISP-Feedback-Loop meldet Beschwerde
  • Auto-Add zu EmailSuppressionList mit reason = complaint
  • Contact bekommt automatisch Unsubscribe-Eintrag mit unsubscribed_via = complaint_auto
  • Activity am Kontakt: „Empfänger hat sich beschwert — automatisch abgemeldet"

Bounce-Webhook-Verarbeitung

  • SMTP-Provider sendet Bounce-Webhook an /api/v1/webhooks/email/bounce
  • Worker verifiziert Signatur, parst Bounce-Type, updated OutboundEmail.delivery_status + bounce_type + bounce_reason_text
  • Hard-Bounce-Handling triggert Suppression-Add

Klartext-Hinweise

  • In Kontakt-Detail-View (sichtbar für crm.write): „Email-Adresse als ungültig markiert (Hard-Bounce am [Datum]). Marketing-Mails werden nicht mehr an diese Adresse gesendet. [Adresse korrigieren] [Adresse trotzdem verwenden]"
  • Bei „Adresse korrigieren" + Speichern: alte Adresse aus Suppression entfernt (falls Kontakt selber dort einzig drinhing), neue Adresse wieder verwendbar

Block H — Unsubscribe & DSGVO

  • Pflicht in jeder Marketing-Mail (DSGVO + CAN-SPAM)
  • Link-URL: /unsubscribe/{unsubscribe_token}
  • Token ist pro OutboundEmail einmalig generiert (32 Zeichen, kryptographisch)
  • Klick → öffentliche Unsubscribe-Page (ohne Login)

Unsubscribe-Page

Zu zeigende Daten:

  • Klartext: „Du wirst von Marketing-Mails von [Tenant-Name] abgemeldet."
  • Bestätigungs-Button: „Abmeldung bestätigen"
  • Optional: Grund-Auswahl (Multi-Select: Zu häufig / Nicht relevant / Spam / Sonstiges)
  • Optional: Freitext-Feedback

Aktion bei Bestätigung:

  • Unsubscribe-Eintrag erzeugt mit scope = all_marketing, unsubscribed_via = link_click
  • Email-Adresse zu EmailSuppressionList (Tenant-spezifisch) hinzugefügt
  • Activity am Contact: „Hat sich von Marketing-Mails abgemeldet am [Datum]"

Klartext-Bestätigung:

  • „Du bist abgemeldet. Wir senden keine weiteren Marketing-Mails an [email-address]. Falls das ein Versehen war: [Wieder anmelden]"

List-Unsubscribe-Header

  • HTTP-Header List-Unsubscribe: <https://app.hivegrid.de/unsubscribe/{token}>, <mailto:unsubscribe@in.hivegrid.de?subject=unsub-{token}>
  • List-Unsubscribe-Post: List-Unsubscribe=One-Click für Gmail/Apple One-Click-Unsubscribe
  • Beide Pfade triggern selben Unsubscribe-Flow

Opt-In-Dokumentation pro Contact

Pflicht-Felder am Contact (kommt aus M1, hier erweitert):

  • marketing_opt_in_at (nullable Timestamp)
  • marketing_opt_in_source (Enum: form_submission | manual_import | implicit_existing_customer | double_opt_in)
  • marketing_opt_in_reference (z.B. Form-Submission-ID, Import-Batch-ID)
  • marketing_opt_in_text_snapshot (Snapshot des Opt-In-Texts zum Zeitpunkt der Zustimmung — für Beweis-Zwecke)

Block bei Versand: Contact ohne marketing_opt_in_at wird automatisch ausgeschlossen (siehe Block D Auto-Exclusion).

Double-Opt-In (Phase 1 für Form-Submissions)

  • Bei Form-Submission mit Opt-In-Checkbox: System sendet Bestätigungs-Mail mit Confirmation-Link
  • Erst nach Klick auf Confirmation-Link wird marketing_opt_in_at gesetzt
  • Confirmation-Link Token-basiert, 7 Tage gültig

Klartext für Tenant-Admin

  • In Suppression-Liste-View: „Diese Adressen erhalten keine Marketing-Mails mehr. Gründe: Hard-Bounce, Beschwerde, manuelle Sperre. [Adresse entfernen]" (Entfernen erfordert email_marketing.admin)
  • Beim Anlegen einer Kampagne mit < 50% Opt-In-Empfängern: Warnung „Nur X% deiner Empfänger haben dokumentiertes Opt-In. Die anderen werden ausgeschlossen. [Mehr lernen]"

Block I — Templates & Sender

Template-Liste (/{tenant}/email-marketing/templates)

Zu zeigende Daten:

  • Template-Name + Beschreibung
  • Letzte Verwendung (Datum + Anzahl Kampagnen)
  • Vorschau-Thumbnail (Auto-Render)
  • Sender-Vorschlag (falls Default gesetzt)

Operationen:

  • Anlegen
  • Editieren (gleicher Editor wie Kampagnen-Builder, ohne Versand-Step)
  • Duplizieren
  • Archivieren
  • Aus Branchen-Template seeden (SHK-Defaults: „Wartungs-Erinnerung", „Newsletter Q4", „Service-Aktion")

Sender-Verwaltung (/{tenant}/email-marketing/senders)

Zu zeigende Daten:

  • Liste aller Sender pro Tenant
  • Pro Sender: From-Name, From-Email, Sending-Domain (mit DKIM-Status), Default-Marker

Operationen:

  • Anlegen (From-Name + From-Email + Sending-Domain wählen)
  • Validierung: From-Email-Domain muss zu Sending-Domain passen
  • Default setzen (max. 1 Default pro Tenant)
  • Archivieren

Klartext-Hinweise:

  • Sender-Anlage ohne verifizierte Domain: „Du musst zuerst eine Sending-Domain einrichten. [Sending-Domain einrichten]" → Link zu M9-Setup
  • Sender-Domain wird in M9 widerrufen: zugehöriger Sender automatisch deaktiviert mit Klartext: „Domain geerkens.de ist nicht mehr verifiziert. Sender deaktiviert. [Domain neu verifizieren]"

Block J — Trigger-Mails (über Automation-Engine)

Action send-marketing-email in M17

  • Automation-Engine bietet Action: „Marketing-Mail senden"
  • Konfiguration:
    • Template wählen (Pflicht)
    • Sender wählen (Pflicht — falls leer: Tenant-Default)
    • Empfänger: Resolution aus Trigger-Kontext (z.B. „an den Contact des getriggerten Deals")
    • Personalisierung: Trigger-Variablen können in Template-Tokens verwendet werden
  • Bei Auslösung: System legt mini-Kampagne mit 1 Empfänger an (Campaign.status = sending mit total_recipients = 1), versendet sofort
  • Tracking läuft analog zu normalen Kampagnen (Open/Click)
  • Auto-Exclusion gilt: wenn Empfänger in Suppression / Unsubscribe → Mail wird nicht gesendet, Activity am Contact: „Trigger-Mail blockiert (Empfänger abgemeldet)"

Use-Cases (Geerkens-relevant)

  • Lead-Erstkontakt: „wenn neuer Lead aus Form → 1h später Bestätigungs-Mail mit Terminvorschlag"
  • Wartungs-Erinnerung: „wenn letzte_wartung > 365 Tage → Wartungs-Erinnerungs-Mail"
  • Deal-Stage-Trigger: „wenn Deal-Stage = ‚Angebot offen' für 7 Tage → Reminder-Mail"

Permission

  • Trigger-Action-Konfiguration: automation.write + email_marketing.write
  • Versand selbst läuft als System-Actor (keine User-Permission-Prüfung pro Auslösung)

Block K — Anti-Spam-Schutz

Daily-Cap pro Tenant

  • Cloud-Plan: 10.000 Mails/Tag (Default, in SubscriptionFeature konfiguriert)
  • Cloud-Plus: 50.000 Mails/Tag
  • Enterprise: Custom
  • Trial: 200 Mails/Tag (verhindert Trial-Abuse)

Bei Überschreitung:

  • Versand stoppt, Status Campaign.status = paused
  • Klartext: „Tägliches Sende-Limit erreicht (10.000/10.000). Versand wird morgen 00:00 Tenant-Zeit fortgesetzt."

Pro-Empfänger-Cap (Anti-Belästigung)

  • Max. 5 Marketing-Mails pro Empfänger pro Woche (Tenant-konfigurierbar in email_marketing.admin)
  • Bei Überschreitung: Empfänger wird auto-excluded mit Reason frequency_cap
  • Klartext im Auto-Exclusion-Report: „X Empfänger ausgeschlossen wegen Frequenz-Cap (zu viele Mails diese Woche)"

Spam-Score-Check (vor Versand)

  • Body wird gegen einfache Heuristik geprüft:
    • Übermäßiger Großschrift-Anteil
    • Übermäßiger Ausrufezeichen-Einsatz
    • Verdächtige Phrasen („KOSTENLOS!!!", „JETZT KAUFEN")
    • Verhältnis Bilder/Text
  • Spam-Score 0-10 angezeigt mit Empfehlungen
  • Score > 7: Warnung mit Block-Option für Tenant-Admin (kann Block überschreiben)

Aufwärm-Phase (Phase 2)

  • Phase 1: Tenant kann sofort 10.000/Tag senden (vorausgesetzt Sending-Domain hat sauberes Reputation-Profil)
  • Phase 2: Auto-Throttle für neue Domains (Tag 1: 100, Tag 7: 1.000, Tag 30: 10.000)

Block L — Permissions

Permission-IDs

Permission Erlaubt
email_marketing.read Kampagnen, Stats, Templates, Sender, Segmente sehen
email_marketing.write Kampagnen erstellen, editieren, versenden; Templates erstellen
email_marketing.admin Sender verwalten, Suppression-Liste verwalten, Daily-Cap konfigurieren, Spam-Override, Sending-Domain mit M9 koordinieren, Frequency-Cap setzen

Bundle-Mapping

Bundle Atomare Permissions
email_marketing.none (keine)
email_marketing.read email_marketing.read
email_marketing.write email_marketing.read + email_marketing.write
email_marketing.admin alle obigen + email_marketing.admin

Anwendung in Routes

  • /{tenant}/email-marketing (Übersicht) → email_marketing.read
  • /{tenant}/email-marketing/campaigns → email_marketing.read
  • /{tenant}/email-marketing/campaigns/new → email_marketing.write
  • /{tenant}/email-marketing/campaigns/:id/edit → email_marketing.write
  • Versand-Bestätigung (final Send-Click) → email_marketing.write + verifizierte Sending-Domain
  • /{tenant}/email-marketing/senders → Read mit email_marketing.read, Write mit email_marketing.admin
  • /{tenant}/email-marketing/suppressions → email_marketing.admin
  • /{tenant}/email-marketing/segments → Read mit email_marketing.read, Write mit email_marketing.write

Klartext-Fehler

  • Versand ohne verifizierte Domain: „Du brauchst eine verifizierte Sending-Domain bevor du Marketing-Mails versendest. [Domain einrichten]"
  • Versand ohne email_marketing.write: Button nicht sichtbar
  • Suppression-Edit ohne email_marketing.admin: Inline-Hinweis: „Suppression-Liste-Änderungen erfordern Admin-Berechtigung"

Activity-Stream-Integration

Activity-Typen die M10 produziert

  • marketing_email_sent — Kampagne an Empfänger gesendet
  • marketing_email_opened — erstes Open
  • marketing_email_clicked — erster Click
  • marketing_email_bounced — Hard- oder Soft-Bounce nach 3 Versuchen
  • marketing_email_unsubscribed — Abmeldung
  • marketing_email_complained — Spam-Beschwerde

Verknüpfungen

  • Activities erscheinen am verknüpften Contact
  • Aggregat-Stats sichtbar in Contact-Detail-View: „Marketing-Engagement: 12 Mails erhalten, 8 geöffnet (66%), 3 geklickt (25%), 0 abgemeldet"

Permission-Wirkung

  • Marketing-Activities mit email_marketing.read
  • Stats-Aggregate auch ohne email_marketing.read sichtbar (User mit crm.read_* sieht: „Marketing-Engagement" — aber nicht Detail welche Kampagne)

Klartext-Hinweise/-Fehler (Querschnitt)

  • Sending-Domain noch nicht verifiziert: „Setup deiner Sending-Domain läuft noch. Wir prüfen alle 5 Minuten. [Status anzeigen]"
  • Domain-Verification-Timeout: „DNS-Einträge nicht gefunden nach 7 Tagen. [Anleitung erneut anzeigen]"
  • Test-Mail nicht angekommen: „Test-Mail an [email] versendet. Falls nach 5 Min nicht angekommen: Spam-Ordner prüfen. [Mehr Hilfe]"
  • Personalisierungs-Token unbekannt: „Token {{custom.foo}} nicht gefunden — wird leer eingesetzt. [Custom-Feld anlegen]"
  • Empty-Recipient-List: „Dein Segment liefert aktuell 0 Empfänger. Filter zu eng? [Segment editieren]"

Phase 2 / spätere Features

  • A/B-Tests (Subject-A vs. Subject-B, automatische Versand des Gewinners an Rest)
  • Automation-Ketten (Sequence-Mailings: Mail 1 → 3 Tage → Mail 2 → 7 Tage → Mail 3 mit Bedingungen)
  • Advanced-Analytics: Geräte-Aufschlüsselung, Geo-Map, Click-Heat-Map
  • Conditional-Content (Block X nur sichtbar wenn Custom-Feld Y = Z)
  • Drag-&-Drop-Builder mit Subframe-Components statt Rich-Text
  • Send-Time-Optimization (KI bestimmt beste Sendezeit pro Empfänger)
  • Reputation-Monitoring (Sender-Score, Postmaster-Tools-Integration)
  • Granulare Unsubscribe-Categories (Newsletter / Promotion / Service-Updates getrennt abmeldbar)
  • Re-Engagement-Kampagnen (auto-erkannte Liste inaktiver Empfänger)

Architektur-Vorschriften (Querschnitt)

  • LP-9: Requirements-pur, kein Layout
  • LP-10: Klartext-Diagnose bei jedem Bounce, Domain-Failure, Cap-Hit
  • LP-11: SMTP-Provider als Adapter (Phase 1: Scaleway TEM oder vergleichbar; Phase 2: Provider-Wechsel ohne Code-Umbau möglich)
  • LP-13: EU-SMTP-Provider (Pflicht für DSGVO)
  • AV #5 Permissions-aware-Default: Kampagnen-Liste filtert nach Permission
  • AV #6 Audit-Trail: Versand, Suppression-Add/Remove, Sender-Anlage werden auditiert
  • DSGVO-Pflicht: Opt-In-Dokumentation, Unsubscribe-Pflicht, Impressum-Pflicht im Footer

Detail-Spec-Status: DRAFT

Erste vollständige Detail-Spec für Modul 10. Phase-1-voll-Modul. Vor Bau: SMTP-Provider-Auswahl (Scaleway TEM evaluieren — alternativ Mailjet EU oder Brevo EU), DKIM-Domain-Verification mit echter Geerkens-Domain testen.

Offene Detail-Punkte (nicht-blockierend):

  • Konkreter SMTP-Provider (LP-13: muss EU sein)
  • Konkrete Daily-Cap-Werte pro Plan (mit Pricing-Definition zu finalisieren)
  • Branchen-Template-Defaults (SHK-Templates: „Wartungs-Erinnerung", „Service-Aktion", „Newsletter-Vorlage" — mit Noah konkretisieren)
  • Branding der Unsubscribe-Page (Tenant-Logo, Tenant-Farben — kommt aus Modul 33)
  • Subframe-UI-Designs (separat)