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

682 lines
27 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: 10
title: Email-Marketing
phase: 1
status: detail-spec-draft
last_updated: 2026-05-08
session_source: brainstorming-session-2026-05-07-2206.md
related_lps: [LP-4, LP-7, LP-9, LP-10, LP-11, LP-13]
spec_style: 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
### Unsubscribe-Link
- 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)