Migrar el correo electrónico transaccional a Cloudflare Email Service

Quiero migrar el correo electrónico saliente de este codebase desde su proveedor actual (Postmark / SES / Resend / SendGrid / Mailgun / etc.) al Servicio de Email de Cloudflare (beta pública, lanzado en abril de 2026). Ayúdame a hacer esto con cuidado. ## Contexto: qué es el Servicio de Email de Cloudflare Una nueva API de correo transaccional de Cloudflare. Endpoint: ``` POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/email/sending/send Authorization: Bearer {API_TOKEN} Content-Type: application/json ``` Cuerpo de la solicitud: ```json { "to": "user@example.com", // string O array de strings "from": "no-reply@yourdomain.com", // string O {"address":"x@y","name":"Display"} "subject": "...", "html": "<p>...</p>", // opcional "text": "...", // opcional (uno de html/text es requerido) "cc": ["..."], // opcional, array "bcc": ["..."], // opcional, array "reply_to": "...", // opcional, string único "headers": {"List-Unsubscribe": "<...>"} // opcional, ej. para newsletters } ``` Respuesta de éxito: HTTP 200 + `{"success":true,"result":{"delivered":[],"queued":[],"permanent_bounces":[]}}`. Fallo: no-200 O `success:false` O `permanent_bounces` no vacío. Siempre verifica los tres. Precios: $5/mes plan Workers Paid + 3,000 correos gratis + $0.35 por cada 1k después. Aproximadamente 5x más barato que Postmark. No hay endpoint de envío por lotes - haz un bucle de envíos individuales. ## Pasos que debes seguir ### 1. Verifica los requisitos previos conmigo Antes de escribir cualquier código, pídeme confirmar: - Tengo un plan Workers Paid de Cloudflare ($5/mes) - He incorporado mi(s) dominio(s) de remitente en el panel de Cloudflare → Email → Email Sending → Onboard Domain (esto agrega automáticamente SPF/DKIM/DMARC + registros MX de cf-bounce) - Tengo un token de API con el alcance `email_sending:write` (creado en https://dash.cloudflare.com → Custom Token) - Tengo mi ID de cuenta de Cloudflare No continúes hasta que tengas estos. ### 2. Recomienda una estrategia de reputación de dominio La mayoría de las aplicaciones deberían dividir los remitentes en 2-3 subdominios para que las quejas de spam en uno no arrastren la entregabilidad de los demás: - `mail.<dominio>` o `members.<dominio>` → transaccional (login, recibos, restablecimiento de contraseña, notificaciones en la app) - `e.<dominio>` → frío/recuperación (carrito abandonado, campañas de re-enganche) - `newsletter.<dominio>` → newsletters opt-in con encabezados List-Unsubscribe Cada subdominio necesita ser incorporado por separado en Cloudflare. Pregúntame cuáles quiero. ### 3. Audita los envíos de correo existentes Usa grep/búsqueda para encontrar cada lugar en este codebase que envía correo. Busca: - Los nombres de clases del SDK del proveedor actual, URLs de API, variables de entorno/config - Patrones genéricos como `mail()`, uso de SMTP, `nodemailer`, etc. Agrupa los hallazgos por tipo/propósito de correo (ej. "login con magic-link", "recibo de pago", "newsletter semanal") en lugar de por archivo. Dime lo que encontraste antes de cambiar cualquier cosa. ### 4. Agrega una única función auxiliar No salpiques llamadas a la API de Cloudflare por todo el codebase. Agrega un único helper (nombre específico del proveedor como `sendEmailViaCloudflare()`) que: - Use por defecto `from` desde una variable de configuración (no lo hardcodees) - Parsee strings `"Nombre <email@dominio>"` a la forma de objeto `{address, name}` de la API - Acepte `cc`/`bcc` como string o array - Acepte un dict de `headers` (los newsletters necesitan `List-Unsubscribe` + `List-Unsubscribe-Post`) - Devuelva `bool` (true en éxito, false en cualquier fallo) - En fallo, registre/alete a algún lugar que pueda ver (Telegram, Sentry, archivo de log - que coincida con lo que el codebase ya hace) - Establezca timeouts de curl/fetch (5s de conexión, 15s total) para que una API de CF atascada no cuelgue la solicitud - Trate `permanent_bounces: [...]` no vacío como un fallo suave ### 5. Migra primero un tipo de correo de bajo riesgo No migres todo de una vez. Elige el tipo de correo de menor riesgo en la auditoría (algo donde caer en spam no te haga perder dinero o usuarios - ej. "alerta interna de admin", "rechazo de foto de perfil") y migra solo ese. Pruébalo de extremo a extremo. Confirma que el correo realmente llega. Solo entonces propón la siguiente migración. ### 6. Impídeme migrar el correo de login todavía Si mi codebase envía correos de login con magic-link o restablecimiento de contraseña, no migres esos a Cloudflare todavía. El Servicio de Email de Cloudflare es muy nuevo (~1 mes desde su lanzamiento al momento de escribir). Su reputación de IP/dominio no está probada. Los correos de login que caen en spam = usuarios bloqueados. Mantén esos en el proveedor actual hasta al menos 3 meses de datos limpios de entregabilidad en los tipos de menor riesgo. Dímelo explícitamente. ### 7. Sugiere límites de commits Después de cada migración exitosa, sugiere un commit de git enfocado con un mensaje claro. No agrupes cambios no relacionados. ## Advertencias importantes que debo mostrarte - Producto beta. Los precios no están completamente finalizados. SLA indefinido. Podría cambiar. - No hay endpoint de lotes. Envíos masivos (newsletters a 1000+ destinatarios) necesitan un bucle - a ~150ms/envío eso es ~2.5min por 1000. Bien para crons, mal para flujos síncronos orientados al usuario. - No hay webhooks de rebote todavía. Superficie de fallos a través del array `permanent_bounces` en el cuerpo de la respuesta. - Lista de supresión auto-gestionada. Rebotes duros, rebotes suaves repetidos y quejas de spam se bloquean. Las supresiones por quejas de spam son difíciles de eliminar (anti-abuso). - No hay logs/dashboard por mensaje todavía. Usa el `messageId` de la respuesta para seguimiento si lo necesito. - Los encabezados List-Unsubscribe se pasan tal cual - el requisito de remitente masivo de Gmail aún se cumple, pero solo si los incluyo en `headers`. ## Tu primera acción Antes de escribir cualquier código: haz el paso 1 (pide los requisitos previos) y el paso 3 (audita los envíos existentes), luego propón el orden de migración con una breve explicación del razonamiento. Espera mi confirmación antes de hacer cambios.