Migriere transaktionale E-Mails zum Cloudflare Email Service

Ich möchte die ausgehende E-Mail dieser Codebasis von ihrem aktuellen Anbieter (Postmark / SES / Resend / SendGrid / Mailgun / etc.) zu Cloudflare Email Service (öffentliche Beta, gestartet April 2026) migrieren. Hilf mir, dies sorgfältig zu tun. ## Kontext: Was Cloudflare Email Service ist Eine neue transaktionale E-Mail-API von Cloudflare. Endpunkt: ``` POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/email/sending/send Authorization: Bearer {API_TOKEN} Content-Type: application/json ``` Anfragekörper: ```json { "to": "user@example.com", // string ODER Array von Strings "from": "no-reply@yourdomain.com", // string ODER {"address":"x@y","name":"Display"} "subject": "...", "html": "<p>...</p>", // optional "text": "...", // optional (eines von html/text erforderlich) "cc": ["..."], // optional, Array "bcc": ["..."], // optional, Array "reply_to": "...", // optional, einzelner String "headers": {"List-Unsubscribe": "<...>"} // optional, z.B. für Newsletter } ``` Erfolgsantwort: HTTP 200 + `{"success":true,"result":{"delivered":[],"queued":[],"permanent_bounces":[]}}`. Fehler: Nicht-200 ODER `success:false` ODER nicht-leeres `permanent_bounces`. Überprüfe immer alle drei. Preise: $5/Monat Workers Paid Plan + 3.000 E-Mails kostenlos + $0,35 pro 1k danach. Ungefähr 5x günstiger als Postmark. Kein Batch-Send-Endpunkt - Schleife für einzelne Sends. ## Schritte, die du befolgen solltest ### 1. Voraussetzungen mit mir verifizieren Bevor du Code schreibst, bitte mich zu bestätigen: - Ich habe einen Cloudflare Workers Paid Plan ($5/Monat) - Ich habe meine Absender-Domain(s) im Cloudflare-Dashboard → E-Mail → E-Mail-Senden → Domain onboarden (dies fügt automatisch SPF/DKIM/DMARC + cf-bounce MX-Records hinzu) - Ich habe einen API-Token mit `email_sending:write`-Bereich (erstellt unter https://dash.cloudflare.com → Custom Token) - Ich habe meine Cloudflare-Konto-ID Fahre nicht fort, bis du diese hast. ### 2. Domain-Reputationsstrategie empfehlen Die meisten Apps sollten Absender auf 2-3 Subdomains aufteilen, sodass Spam-Beschwerden auf einer nicht die Zustellbarkeit auf anderen beeinträchtigen: - `mail.<domain>` oder `members.<domain>` → transaktional (Login, Belege, Passwort-Reset, In-App-Benachrichtigungen) - `e.<domain>` → Cold/Recovery (verlassener Warenkorb, Win-back-Kampagnen) - `newsletter.<domain>` → Opt-in-Newsletter mit List-Unsubscribe-Headern Jede Subdomain muss separat in Cloudflare onboardet werden. Frage mich, welche ich möchte. ### 3. Bestehende E-Mail-Sends prüfen Verwende grep/search, um jede Stelle in dieser Codebasis zu finden, die E-Mails sendet. Suche nach: - Den SDK-Klassennamen des aktuellen Anbieters, API-URLs, Env/Config-Variablen - Generischen Mustern wie `mail()`, SMTP-Nutzung, `nodemailer`, etc. Gruppiere Ergebnisse nach E-Mail-Typ/Zweck (z.B. "Magic-Link-Login", "Zahlungsbeleg", "Wöchentlicher Newsletter") statt nach Datei. Teile mir mit, was du gefunden hast, bevor du etwas änderst. ### 4. Eine einzelne Hilfsfunktion hinzufügen Streue keine Cloudflare-API-Aufrufe über die Codebasis. Füge einen Helfer hinzu (anbieterspezifischer Name wie `sendEmailViaCloudflare()`), der: - `from` standardmäßig aus einer Config-Variable setzt (nicht hartcodieren) - `"Name <email@domain>"`-Strings in die API-Form `{address, name}` parst - `cc`/`bcc` als String oder Array akzeptiert - Ein `headers`-Dict akzeptiert (Newsletter benötigen `List-Unsubscribe` + `List-Unsubscribe-Post`) - `bool` zurückgibt (true bei Erfolg, false bei jedem Fehler) - Bei Fehler protokolliert/alertet, wo ich es sehen kann (Telegram, Sentry, Log-Datei - passend zu dem, was die Codebasis bereits tut) - curl/fetch-Timeouts setzt (5s Verbindung, 15s gesamt), sodass eine hängende CF-API die Anfrage nicht blockieren kann - Nicht-leeres `permanent_bounces: [...]` als weichen Fehler behandelt ### 5. Zuerst einen E-Mail-Typ mit geringem Risiko migrieren Migriere nicht alles auf einmal. Wähle den E-Mail-Typ mit dem geringsten Risiko aus der Prüfung (etwas, bei dem Spam-Landung kein Geld oder Nutzer kosten würde - z.B. "Interner Admin-Alert", "Profilfoto-Ablehnung") und migriere nur diesen. Teste ihn Ende-zu-Ende. Bestätige, dass die E-Mail tatsächlich ankommt. Nur dann schlage die nächste Migration vor. ### 6. Mich davon abhalten, Login-E-Mails zu migrieren Wenn meine Codebasis Magic-Link-Login- oder Passwort-Reset-E-Mails sendet, migriere diese noch nicht zu Cloudflare. Cloudflare Email Service ist brandneu (~1 Monat alt zum Zeitpunkt des Schreibens). Seine IP-/Domain-Reputation ist unbewiesen. Login-E-Mails, die im Spam landen = Nutzer ausgesperrt. Behalte diese beim aktuellen Anbieter, bis mindestens 3 Monate sauberer Zustellbarkeitsdaten für die Typen mit geringerem Risiko vorliegen. Sage mir dies explizit. ### 7. Commit-Grenzen vorschlagen Nach jeder erfolgreichen Migration schlage einen fokussierten Git-Commit mit klarer Nachricht vor. Bündele keine unzusammenhängenden Änderungen. ## Wichtige Hinweise, die ich dir mitteilen soll - Beta-Produkt. Preise nicht vollständig finalisiert. SLA undefiniert. Könnte sich ändern. - Kein Batch-Endpunkt. Massen-Sends (Newsletter an 1000+ Empfänger) benötigen eine Schleife - bei ~150ms/Send sind das ~2,5min pro 1000. Gut für Crons, schlecht für synchrone nutzerorientierte Abläufe. - Noch keine Bounce-Webhooks. Fehler über das `permanent_bounces`-Array im Antwortkörper sichtbar machen. - Unterdrückungsliste automatisch verwaltet. Harte Bounces, wiederholte weiche Bounces und Spam-Beschwerden werden blockiert. Spam-Beschwerde-Unterdrückungen sind schwer zu entfernen (Anti-Missbrauch). - Noch keine Pro-Message-Logs/Dashboard. Verwende die `messageId` aus der Antwort für Tracking, falls benötigt. - List-Unsubscribe-Header werden wörtlich durchgereicht - Gmail-Bulk-Sender-Anforderung bleibt erfüllt, aber nur, wenn ich sie in `headers` aufnehme. ## Deine erste Aktion Bevor du Code schreibst: Führe Schritt 1 (Voraussetzungen erfragen) und Schritt 3 (bestehende Sends prüfen) durch, dann schlage die Migrationsreihenfolge mit kurzer Begründung vor. Warte auf meine Bestätigung, bevor du Änderungen vornimmst.