# React-Email Migration
**Status:** completed
**Task-ID:** #75
**Phase:** 10
**Estimated Effort:** 1-2 Wochen
**Owner:** agent/10-react-email
## Problem
Die existierenden Transactional-Email-Templates in `packages/mail/src/templates/transactional.ts` sind handgeschriebene HTML-Strings mit manuellen `escapeHtml`-Aufrufen für User-Content. Konkrete Schmerzpunkte:
- **Audit-Findings**: Manuelles HTML-Escaping ist fehleranfällig. Reviews finden regelmäßig vergessene Escape-Aufrufe (z.B. wenn ein neuer Template-Parameter `signaturName` hinzukommt und der Entwickler die Escape-Pflicht übersieht). Das ist eine permanente XSS-Klasse in Outbound-Mails (HTML-Renderer in einigen Mail-Clients sind aggressiver als oft angenommen).
- **Maintenance-Nightmare**: Jede Brand-Änderung (Logo-Update, Primary-Color-Wechsel pro Tenant) erfordert HTML-String-Edits in einer monolithischen Datei. Kein Component-Reuse zwischen Templates möglich (Header, Footer, Button, CTA-Block werden jedes Mal neu inline-zusammengebaut).
- **Keine Live-Preview**: Entwickler müssen die Mail tatsächlich versenden (oder MailHog-Container starten) um das Rendering zu sehen. Iteration ist langsam.
- **Historische Phase-05-Annahme:** Marketing-Funnel-Phase-3 plante React-Email als Basis für Email-Sequences-Templates (Drip-Campaigns, Onboarding-Sequences). React-Email ist inzwischen abgeschlossen; der aktuelle Email-Sequences-Blocker liegt im sequence-spezifischen Renderer und Mail-Adapter, siehe `docs/features/email-sequences.md`.
- **Plain-Text-Fallback** wird heute nur sporadisch generiert. React-Email rendert automatisch eine `@react-email/render`-kompatible Plain-Text-Variante aus dem JSX-Tree.
- **Brand-Theming pro Tenant** (Logo, Primary-Color, Font) ist nur als Header-Token-Replacement implementiert — keine echte Component-Prop-Pipeline.
Betroffene Codestellen:
- `packages/mail/src/templates/transactional.ts` — alle Transactional-Templates (Welcome, Magic-Link, Password-Reset, Subscription-Success/Failed, Invitation, Invoice-Sent, Tenant-Notification)
- `packages/mail/src/templates/transactional.test.ts` — Tests, die String-Matching auf HTML-Output machen (müssen auf Snapshot-Tests migriert werden)
- `packages/mail/src/queue.ts` — Renderer-Aufrufe, müssen auf `@react-email/render` umgestellt werden
- `packages/mail/src/mailjet.ts` — Bestätigt MIME-Multipart-Versand mit `text` + `html` Parts (React-Email liefert beides)
## Depends on
- `01-tech-debt-foundation/dep-updates.md` — React-Email braucht React 18.3+ und kompatible TypeScript-Version; Dep-Updates müssen vorher durch sein
- `02-observability/sentry-wiring-api-worker.md` — Render-Fehler in Templates sollen via Sentry erfasst werden, sonst tappen wir blind bei Production-Template-Bugs
**Nicht benötigt aber empfehlenswert:**
- `02-observability/logging-migration.md` — saubere Render-Logs
## Blocks
- `05-business-features/marketing-funnel-phase-3.md` — historische Referenz: Email-Sequences nutzten React-Email als Template-Basis; aktuelle offene Produktionsarbeit liegt im sequence-spezifischen Renderer/Mail-Adapter.
- Indirekt: zukünftige Notification-Center-Erweiterungen (HTML-Email-Digests aus In-App-Notifications) bauen auf den React-Components auf
## Approach
**Neue Subdirectory `packages/mail/src/templates-react/`** mit folgender Architektur:
1. **React-Email-Setup**:
- `@react-email/components` (Body, Container, Section, Row, Column, Text, Heading, Button, Img, Link, Hr, Preview, Tailwind) als Component-Library
- `@react-email/render` als Renderer (liefert HTML + Plain-Text)
- Tailwind-Inline-Styles via `@react-email/tailwind`-Wrapper (Browser-Compatible-Subset, Stylesheet wird inline in jedes Element gebrannt — Email-Client-kompatibel)
2. **Layout-Components** (`packages/mail/src/templates-react/_layout/`):
- `BaseLayout` — Wrapper mit Body + Container + Preview-Header
- `Header` — Logo + optional Tenant-Brand-Color als Background
- `Footer` — Unsubscribe-Link (CAN-SPAM/DSGVO-Pflicht), Company-Adresse, Social-Links
- `Button` — CTA-Button mit Brand-Color-Prop
- `InfoBox` — Boxed-Section für „wichtige Informationen"
3. **Migration aller Existing Templates** (`packages/mail/src/templates-react/transactional/`):
- `WelcomeEmail.tsx` — Account-Aktivierung
- `MagicLinkEmail.tsx` — Magic-Link für Login (`actionUrl` als Prop)
- `PasswordResetEmail.tsx` — Reset-Link
- `SubscriptionSuccessEmail.tsx` — Stripe-Subscription-Confirmation
- `SubscriptionFailedEmail.tsx` — Stripe-Failed-Payment-Notice
- `InvitationEmail.tsx` — Tenant-Member-Invite mit Tenant-Brand-Theming
- `InvoiceSentEmail.tsx` — Stripe-Invoice-PDF-Notification
- `TenantNotificationEmail.tsx` — generische Tenant-Notification-Template (für In-App-Notifications, die per Email gesendet werden)
4. **Marketing-Campaign-Template-Base** (`packages/mail/src/templates-react/marketing/`):
- `CampaignBaseLayout` — generisches Marketing-Layout mit Brand-Hero, CTA-Buttons, Image-Slots
- Wird in Phase-05-Marketing-Funnel-Phase-3 als Foundation für Drip-Sequences verwendet
- Plain-Text-Fallback ist automatisch (React-Email rendert Text-Variante aus JSX-Tree)
5. **Brand-Theming via Props**:
- Jedes Template nimmt `brand: { logoUrl?: string; primaryColor?: string; fontFamily?: string; tenantName?: string }` als Prop
- Tenant-Brand-Config wird via existing `packages/brand`-Package geladen
- Sensible Defaults wenn `brand` undefined (Plattform-Default-Theme)
- Primary-Color wird automatisch auf Button, Header-Accent, Link-Color angewendet
6. **Plain-Text-Fallback** (automatisch):
- `render(, { plainText: true })` aus `@react-email/render`
- Wird im `queue.ts`-Renderer-Pfad immer mit-gerendert und als `text`-Part im MIME-Multipart versendet
7. **Live-Preview-Workflow**:
- `pnpm email:preview` startet React-Email-Dev-Server (`react-email dev` aus `@react-email/preview`)
- Localhost:3001 zeigt alle Templates mit Hot-Reload und Sample-Props
- Sample-Props in `packages/mail/src/templates-react/_previews/.preview.tsx`
8. **Storybook-Stories**:
- Jedes Template hat eine Storybook-Story in `packages/mail/src/templates-react/.stories.tsx` (sobald Phase 08 Storybook fertig ist; bis dahin nur React-Email-Preview)
- Zeigt Brand-Theme-Varianten (Default, Tenant-A, Tenant-B mit jeweils anderem Logo/Color)
9. **Sicherheit**:
- User-Content wird durch React's Default-Escaping automatisch sicher — eliminiert alle manuellen `escapeHtml`-Aufrufe und damit die ganze Audit-Klasse
- `actionUrl`-Validation in Component-Props: nur `https://`-URLs erlaubt, sonst Throw (verhindert `javascript:`-Injection in Magic-Links)
- `dangerouslySetInnerHTML` ist verboten in allen Templates (ESLint-Rule aktiviert)
10. **Tests**:
- Snapshot-Tests gegen gerendertes HTML pro Template (Vitest + `@react-email/render`)
- Snapshot-Tests pro Brand-Theme-Variante
- Edge-Case-Tests: lange Texte, fehlende optionale Props, Unicode-Content (Emoji, RTL-Sprachen)
- Optional Integration: `litmus`- oder `email-on-acid`-CLI für Cross-Client-Rendering-Smoke-Tests (manuell triggerbar, nicht in CI default)
**Warum nicht Alternativen:**
- ❌ MJML: weniger React-Idiom, eigene DSL, schlechtere TypeScript-Integration, kein Hot-Reload-Dev-Server gleich gut
- ❌ Eigene JSX-zu-Email-HTML-Pipeline: React-Email löst alle Edge-Cases (Outlook-Quirks, Gmail-Image-Limits, Dark-Mode-Support) bereits; nicht wert das nachzubauen
- ❌ Bei Plain-HTML-Strings bleiben: Audit-Findings bleiben permanent, kein Component-Reuse, keine Live-Preview
- ❌ Maizzle: Tailwind-orientiert aber Static-Site-Generator-Modell, weniger React-Component-Modell
## Implementation Steps
1. **Dependencies installieren**
- Files: `packages/mail/package.json`
- Add: `@react-email/components`, `@react-email/render`, `@react-email/preview`, `@react-email/tailwind`
- Add Dev-Dep: `react-email` (CLI für Dev-Server)
- Commit: `10-compliance-polish/react-email: add @react-email dependencies`
2. **Setup Subdirectory + Layout-Components**
- Files: `packages/mail/src/templates-react/_layout/BaseLayout.tsx`, `Header.tsx`, `Footer.tsx`, `Button.tsx`, `InfoBox.tsx`, plus `_layout/index.ts`
- Layout-Components mit Brand-Prop-Threading
- Unit-Tests: `BaseLayout.test.tsx` (Snapshot mit Default + Custom-Brand)
- Commit: `10-compliance-polish/react-email: scaffold templates-react layout components`
3. **WelcomeEmail Template**
- Files: `packages/mail/src/templates-react/transactional/WelcomeEmail.tsx`, `.test.tsx`, `_previews/WelcomeEmail.preview.tsx`
- Snapshot-Test, Brand-Theme-Test
- Commit: `10-compliance-polish/react-email: migrate welcome email to react-email`
4. **MagicLinkEmail + PasswordResetEmail Templates**
- Files: `MagicLinkEmail.tsx`, `PasswordResetEmail.tsx`, plus Tests + Previews
- `actionUrl`-Validation als Prop-Typ + Runtime-Check (`https:`-only)
- Commit: `10-compliance-polish/react-email: migrate auth-flow emails (magic-link, password-reset)`
5. **Subscription-Emails (Success, Failed)**
- Files: `SubscriptionSuccessEmail.tsx`, `SubscriptionFailedEmail.tsx`, plus Tests + Previews
- Stripe-Plan-Display, Next-Billing-Date
- Commit: `10-compliance-polish/react-email: migrate stripe subscription notification emails`
6. **InvitationEmail + InvoiceSentEmail**
- Files: `InvitationEmail.tsx`, `InvoiceSentEmail.tsx`, plus Tests + Previews
- Invitation mit Tenant-Brand-Theme (Logo, Color), Invoice mit PDF-Link
- Commit: `10-compliance-polish/react-email: migrate invitation and invoice emails`
7. **TenantNotificationEmail (generisch)**
- Files: `TenantNotificationEmail.tsx`, plus Tests + Preview
- Akzeptiert `title`, `body` (Markdown via `react-markdown` in ``-Wrapper, sicheres Escaping), `actionUrl`, `actionLabel`
- Commit: `10-compliance-polish/react-email: migrate tenant notification email`
8. **Marketing-Campaign-Base-Template**
- Files: `packages/mail/src/templates-react/marketing/CampaignBaseLayout.tsx`, `_previews/CampaignBaseLayout.preview.tsx`, Test
- Hero-Section, CTA-Buttons, Image-Slots, Unsubscribe-Footer (CAN-SPAM/DSGVO-Pflicht)
- Commit: `10-compliance-polish/react-email: add marketing campaign base layout for funnel sequences`
9. **Renderer-Integration in queue.ts**
- Files: `packages/mail/src/queue.ts`, `packages/mail/src/queue.test.ts`
- Renderer-Aufruf umstellen von Template-String-Render auf `render(, { plainText: false })` + zweiter Aufruf mit `plainText: true`
- MIME-Multipart-Versand mit beiden Varianten
- Re-Export-Wrapper für Backwards-Compat: alte `renderTransactional(templateName, props)`-Signatur dispatcht auf React-Component
- Tests: Snapshot der gerenderten HTML- und Text-Outputs
- Commit: `10-compliance-polish/react-email: integrate render pipeline in mail queue`
10. **Live-Preview-Setup**
- Files: `packages/mail/package.json` (Script-Eintrag `email:preview`), `packages/mail/react-email.config.ts`
- `pnpm email:preview` startet React-Email-Dev-Server auf Port 3001
- Doku: `packages/mail/README.md` ergänzen mit Preview-Workflow
- Commit: `10-compliance-polish/react-email: add live preview workflow`
11. **Alte Templates entfernen oder reduzieren**
- Files: `packages/mail/src/templates/transactional.ts` (loeschen oder auf Re-Export-Shim reduzieren), `packages/mail/src/templates/transactional.test.ts` (loeschen), `packages/mail/src/templates/transactional.locale.test.ts` (loeschen oder auf React-Templates portieren)
- Wenn andere Aufrufer noch direkt auf String-Templates zugreifen: in separatem Commit migrieren
- Commit: `10-compliance-polish/react-email: remove legacy string-based transactional templates`
12. **Doku + Contributing-Guide**
- Files: `docs/contributing/email-templates.md`
- Erklärt: Component-Library, wie neue Templates angelegt werden, Brand-Theming-Pattern, Live-Preview, Snapshot-Test-Pflicht, `actionUrl`-Validation, `dangerouslySetInnerHTML`-Verbot
- Commit: `10-compliance-polish/react-email: document email-template contribution workflow`
## Test Requirements
- **Unit-Tests pro Template:** Snapshot-Test gegen gerenderten HTML-Output (Vitest), plus Snapshot pro Brand-Theme-Variante (Default, Tenant-A, Tenant-B)
- **Edge-Case-Tests:** lange Texte (Wrap-Verhalten), fehlende optionale Props (Default-Fallback), Unicode-Content (Emoji + RTL-Strings)
- **Plain-Text-Snapshot:** parallel zum HTML-Snapshot ein Plain-Text-Snapshot für jeden Template
- **Renderer-Integration-Test:** `queue.test.ts` prüft End-to-End: Template-Name + Props → MIME-Multipart-Output mit `text` und `html`-Part
- **Sicherheits-Tests:**
- `actionUrl` mit `javascript:`-Scheme wird abgelehnt (Throw)
- User-Content mit `