Migrer les e-mails transactionnels vers le service e-mail de Cloudflare

Je veux migrer les emails sortants de cette base de code de son fournisseur actuel (Postmark / SES / Resend / SendGrid / Mailgun / etc.) vers Cloudflare Email Service (bêta publique, lancé en avril 2026). Aide-moi à faire cela avec précaution. ## Contexte : ce qu'est Cloudflare Email Service Une nouvelle API d'email transactionnel de Cloudflare. Endpoint : ``` POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/email/sending/send Authorization: Bearer {API_TOKEN} Content-Type: application/json ``` Corps de la requête : ```json { "to": "user@example.com", // string OU tableau de strings "from": "no-reply@yourdomain.com", // string OU {"address":"x@y","name":"Display"} "subject": "...", "html": "<p>...</p>", // optionnel "text": "...", // optionnel (un de html/text requis) "cc": ["..."], // optionnel, tableau "bcc": ["..."], // optionnel, tableau "reply_to": "...", // optionnel, string unique "headers": {"List-Unsubscribe": "<...>"} // optionnel, ex. pour newsletters } ``` Réponse de succès : HTTP 200 + `{"success":true,"result":{"delivered":[],"queued":[],"permanent_bounces":[]}}`. Échec : non-200 OU `success:false` OU `permanent_bounces` non vide. Vérifie toujours les trois. Tarification : plan Workers Paid à 5 $/mois + 3 000 emails gratuits + 0,35 $ par 1 000 après. Environ 5x moins cher que Postmark. Pas d'endpoint d'envoi par lots - boucle sur les envois individuels. ## Étapes à suivre ### 1. Vérifier les prérequis avec moi Avant d'écrire du code, demande-moi de confirmer : - J'ai un plan Cloudflare Workers Paid (5 $/mois) - J'ai intégré mon/mes domaine(s) d'expéditeur dans le tableau de bord Cloudflare → Email → Email Sending → Onboard Domain (cela ajoute automatiquement SPF/DKIM/DMARC + enregistrements MX cf-bounce) - J'ai un jeton API avec le scope `email_sending:write` (créé sur https://dash.cloudflare.com → Custom Token) - J'ai mon ID de compte Cloudflare Ne continue pas tant que tu n'as pas ces éléments. ### 2. Recommander une stratégie de réputation de domaine La plupart des applications devraient répartir les expéditeurs sur 2-3 sous-domaines afin que les plaintes de spam sur l'un n'affectent pas la délivrabilité des autres : - `mail.<domain>` ou `members.<domain>` → transactionnel (connexion, reçus, réinitialisation de mot de passe, notifications in-app) - `e.<domain>` → froid/récupération (panier abandonné, campagnes de reconquête) - `newsletter.<domain>` → newsletters opt-in avec en-têtes List-Unsubscribe Chaque sous-domaine doit être intégré séparément dans Cloudflare. Demande-moi lesquels je veux. ### 3. Auditer les envois d'emails existants Utilise grep/recherche pour trouver chaque endroit dans cette base de code qui envoie des emails. Recherche : - Les noms de classes SDK du fournisseur actuel, les URLs API, les variables d'environnement/config - Les modèles génériques comme `mail()`, utilisation SMTP, `nodemailer`, etc. Regroupe les résultats par type/objectif d'email (ex. "connexion par lien magique", "reçu de paiement", "newsletter hebdomadaire") plutôt que par fichier. Dis-moi ce que tu as trouvé avant de changer quoi que ce soit. ### 4. Ajouter une fonction d'aide unique Ne disperse pas les appels API Cloudflare dans toute la base de code. Ajoute une seule fonction d'aide (nom spécifique au fournisseur comme `sendEmailViaCloudflare()`) qui : - Définit `from` par défaut à partir d'une variable de config (ne pas coder en dur) - Analyse les chaînes `"Nom <email@domaine>"` dans la forme objet `{address, name}` de l'API - Accepte `cc`/`bcc` comme string ou tableau - Accepte un dictionnaire `headers` (les newsletters nécessitent `List-Unsubscribe` + `List-Unsubscribe-Post`) - Retourne `bool` (true en cas de succès, false en cas d'échec) - En cas d'échec, journalise/alerte quelque part où je peux voir (Telegram, Sentry, fichier journal - correspond à ce que la base de code fait déjà) - Définit des délais d'expiration curl/fetch (5 s de connexion, 15 s au total) pour qu'une API CF bloquée ne puisse pas suspendre la requête - Traite `permanent_bounces: [...]` non vide comme un échec léger ### 5. Migrer d'abord un type d'email à faible enjeu Ne migre pas tout à la fois. Choisis le type d'email au plus faible enjeu dans l'audit (quelque chose où atterrir dans le spam ne te ferait pas perdre d'argent ou d'utilisateurs - ex. "alerte admin interne", "rejet de photo de profil") et migre uniquement celui-ci. Teste-le de bout en bout. Confirme que l'email arrive réellement. Seulement ensuite propose la migration suivante. ### 6. M'empêcher de migrer les emails de connexion pour l'instant Si ma base de code envoie des emails de connexion par lien magique ou de réinitialisation de mot de passe, ne migre pas ceux-ci vers Cloudflare pour l'instant. Cloudflare Email Service est tout nouveau (~1 mois au moment de l'écriture). Sa réputation IP/domaine n'est pas prouvée. Les emails de connexion atterrissant dans le spam = utilisateurs verrouillés. Garde-les sur le fournisseur actuel jusqu'à au moins 3 mois de données de délivrabilité propres sur les types à plus faible enjeu. Dis-moi cela explicitement. ### 7. Suggérer des limites de commit Après chaque migration réussie, suggère un commit git ciblé avec un message clair. Ne regroupe pas de changements sans rapport. ## Mises en garde importantes à te signaler - Produit en bêta. Tarification pas entièrement finalisée. SLA non défini. Peut changer. - Pas d'endpoint par lots. Les envois massifs (newsletters à 1000+ destinataires) nécessitent une boucle - à ~150 ms/envoi, cela fait ~2,5 min par 1000. Bien pour les crons, mauvais pour les flux synchrones côté utilisateur. - Pas encore de webhooks de rebond. Signale les échecs via le tableau `permanent_bounces` du corps de réponse. - Liste de suppression gérée automatiquement. Les rebonds durs, les rebonds légers répétés et les plaintes de spam sont bloqués. Les suppressions pour plaintes de spam sont difficiles à retirer (anti-abus). - Pas encore de journaux/tableau de bord par message. Utilise le `messageId` de la réponse pour le suivi si j'en ai besoin. - Les en-têtes List-Unsubscribe sont transmis verbatim - l'exigence de l'expéditeur en volume de Gmail est toujours satisfaite, mais seulement si je les inclus dans `headers`. ## Ta première action Avant d'écrire du code : fais l'étape 1 (demande les prérequis) et l'étape 3 (audit des envois existants), puis propose l'ordre de migration avec une brève explication du raisonnement. Attends ma confirmation avant de faire des modifications.