# 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(