Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,681 @@
|
||||
---
|
||||
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)
|
||||
Reference in new issue
Block a user