Configuración del correo

Empieza por la visión general de autoalojamiento si prefieres ver antes la arquitectura completa, y combina esta guía con la de almacenamiento para configurar juntas las subidas y el correo.

Fluxo admite tanto resend como ses como transportes de correo transaccional. Esa elección se controla con EMAIL_TRANSPORT_PROVIDER.

Esta página es deliberadamente neutral respecto al proveedor, porque el correo es una responsabilidad, no un fabricante. La aplicación genera los correos igual en los dos casos: React Email sigue produciendo el contenido y la elección de proveedor solo cambia el transporte y la fontanería de entrada que lo rodea.

Elige tu proveedor

Los dos proveedores están soportados y los dos conviven bien hoy en el código.

• resend es el valor por defecto y encaja bien si quieres el camino de correo alojado más sencillo
• ses es la opción nativa de AWS y encaja bien si quieres la infraestructura de correo en tu propia cuenta de AWS

El interruptor principal del transporte es:

CopiarEMAIL_TRANSPORT_PROVIDER=resend

o:

CopiarEMAIL_TRANSPORT_PROVIDER=ses

Comparativa de capacidades actual

Esta es la diferencia práctica entre los dos transportes en la implementación actual:

• los dos admiten el envío transaccional a través de la misma API de correo de la aplicación
• los dos funcionan con EMAIL_TRANSPORT_PROVIDER
• los dos conviven con un enrutado de respuestas consciente del proveedor para el correo nuevo
• el análisis de las respuestas entrantes acepta tanto el dominio de entrada de Resend como el de SES, lo que hace posible el solape
• Resend sigue teniendo sus propios ayudantes de audiencias y contactos, al margen del interruptor de transporte
• en este despliegue, SES todavía no admite envíos programados ni etiquetas de proveedor

Cómo funciona el correo en Fluxo

Elijas el proveedor que elijas, la forma del flujo en la aplicación no cambia:

1. React Email genera el mensaje saliente dentro de la aplicación.
2. EMAIL_TRANSPORT_PROVIDER selecciona el transporte activo para los envíos nuevos.
3. Las nuevas direcciones de respuesta se generan a partir del dominio de entrada del proveedor activo.
4. Las respuestas entrantes y los eventos de ciclo de vida se normalizan de vuelta hacia la API.
5. La API convierte las respuestas entrantes en mensajes de la conversación y registra los eventos de rebote, queja y fallo para la supresión.

Ahora mismo los routers de los dos proveedores aceptan los eventos email.delivered pero, a propósito, no los guardan. No trates esta integración como un seguimiento de entrega; si necesitas confirmación de entrega, usa los registros del proveedor.

Eso significa que Resend y SES pueden convivir durante una migración o un periodo de solape:

• el correo saliente nuevo sigue al proveedor activo
• las cadenas de respuesta antiguas de Resend pueden seguir funcionando por el camino de entrada de Resend
• SES se puede activar y verificar antes de cambiar la bandera de transporte

Entorno de correo compartido

Estas variables de entorno importan elijas el proveedor que elijas:

CopiarEMAIL_TRANSPORT_PROVIDER=resend
EMAIL_NOTIFICATION_FROM=support@example.com
EMAIL_MARKETING_FROM=hello@example.com
EMAIL_RESEND_INBOUND_DOMAIN=inbound.example.com
EMAIL_SES_INBOUND_DOMAIN=ses-inbound.example.com

Qué controlan:

• EMAIL_TRANSPORT_PROVIDER: selecciona el transporte transaccional activo para el correo saliente nuevo
• EMAIL_NOTIFICATION_FROM: la dirección del remitente para el correo de tipo notificación
• EMAIL_MARKETING_FROM: la dirección del remitente para el correo de tipo marketing
• EMAIL_RESEND_INBOUND_DOMAIN: el dominio de respuestas entrantes que usa el camino de Resend
• EMAIL_SES_INBOUND_DOMAIN: el dominio de respuestas entrantes que usa el camino de SES

Aunque solo pienses usar un proveedor, conviene entender los dos dominios: el análisis de entrada acepta ambos y el solape es un estado soportado.

Configuración de Resend

Hoy Resend es el transporte por defecto de la aplicación. Es una buena elección si quieres un proveedor alojado sencillo sin montar de entrada la infraestructura de SES.

Qué configurar

Define las variables de entorno propias de Resend:

CopiarEMAIL_TRANSPORT_PROVIDER=resend
RESEND_API_KEY=re_...
RESEND_WEBHOOK_SECRET=whsec_...
EMAIL_RESEND_INBOUND_DOMAIN=inbound.example.com
EMAIL_NOTIFICATION_FROM=support@example.com
EMAIL_MARKETING_FROM=hello@example.com

Qué espera la aplicación de Resend

Para el camino de Resend, Fluxo espera:

• una clave de API válida para los envíos transaccionales salientes
• un dominio de remitente verificado para las direcciones from que uses
• un dominio de entrada para gestionar las respuestas
• entrega de webhooks hacia las rutas de webhook de Resend que ya existen

Qué se espera de los webhooks

El camino heredado de Resend se mantiene precisamente para que pueda seguir atendiendo:

• las respuestas a hilos antiguos enviados con Resend
• los eventos de ciclo de vida de Resend durante los periodos de solape

Si mantienes Resend activo mientras evalúas SES, no quites todavía su configuración de entrada.

Configuración de SES

SES es la opción nativa de AWS y el camino recomendado si quieres que todo el stack de correo viva en tu propia cuenta de AWS.

Por qué elegir SES

SES encaja muy bien con el autoalojamiento porque le da a Fluxo todas las piezas que necesita:

• envío transaccional saliente
• gestión de las respuestas entrantes
• webhooks de entrega, rebote, queja y fallo (la entrega se acepta pero no se guarda)
• infraestructura que corre en tu cuenta de AWS en lugar de en un SaaS de correo aparte

Camino de configuración recomendado

El módulo de SES está en infra/aws/ses-email-setup.

Aprovisiona:

• las identidades y la configuración de SES
• un dominio de respuestas entrantes
• un bucket de S3 para el correo entrante en bruto
• la fontanería de SNS y SQS
• pequeñas funciones Lambda de puente escritas en TypeScript
• credenciales de IAM para el envío saliente con SES

Paso 1: rellena las variables de Terraform

Entra en el módulo:

Copiarcd infra/aws/ses-email-setup

Copia el archivo de variables de ejemplo:

Copiarcp terraform.tfvars.example terraform.dev.tfvars

Después rellena los valores propios de tu entorno:

Copiaraws_region           = "us-east-1"
environment          = "dev"
sender_domain        = "example.com"
inbound_domain       = "ses-inbound.example.com"
inbound_bucket_name  = "fluxo-dev-ses-example"
api_webhook_base_url = "https://api.example.com"
ses_webhook_secret   = "replace-me"
route53_zone_id      = "Z1234567890"

Paso 2: instala las dependencias y despliega

El módulo compila las lambdas de puente desde el monorepo con bun build, así que asegúrate de tener las dependencias instaladas en la raíz del repositorio:

Copiarbun install

Después inicializa y aplica:

Copiarterraform init
terraform apply -var-file="terraform.dev.tfvars"

Paso 3: comprueba el DNS y la salud de la identidad de SES

No sigas hasta que la identidad de remitente y el dominio de entrada estén sanos.

Si usas la automatización de Route53, Terraform puede crear los registros por ti. Si no, tendrás que añadir las salidas a mano.

Como mínimo, verifica:

• el registro de verificación del remitente de SES
• los registros DKIM
• los registros MAIL FROM
• el registro MX de entrada de tu dominio de respuestas de SES

Paso 4: configura el entorno de ejecución de SES

Define las variables de entorno propias de SES:

CopiarEMAIL_TRANSPORT_PROVIDER=resend
EMAIL_NOTIFICATION_FROM=support@example.com
EMAIL_MARKETING_FROM=hello@example.com
EMAIL_RESEND_INBOUND_DOMAIN=inbound.example.com
EMAIL_SES_INBOUND_DOMAIN=ses-inbound.example.com
SES_REGION=us-east-1
SES_ACCESS_KEY_ID=AKIA...
SES_SECRET_ACCESS_KEY=...
SES_CONFIGURATION_SET=fluxo-email-dev
SES_WEBHOOK_SECRET=replace-me

Qué significan en SES:

• EMAIL_SES_INBOUND_DOMAIN: el dominio de respuestas entrantes que gestiona SES
• SES_REGION: la región de AWS que se usa para el envío saliente con SES
• SES_ACCESS_KEY_ID y SES_SECRET_ACCESS_KEY: las credenciales que se usan para los envíos salientes
• SES_CONFIGURATION_SET: el conjunto de configuración de SES que crea Terraform
• SES_WEBHOOK_SECRET: el secreto compartido con el que se firman las peticiones de webhook del puente

Guarda las claves del proveedor y los secretos de webhook en el gestor de secretos de tu despliegue, no en un .env subido al repositorio. Prefiere roles de carga de trabajo antes que claves estáticas de SES cuando tu runtime lo permita, rota las credenciales de larga duración y mantén activa la ventana de marca de tiempo y antirreplay del puente. Además, las cuentas de SES tienen que salir del modo sandbox y tener límites de envío suficientes antes de pasar a producción.

Paso 5: entiende el puente de webhooks

El camino de SES usa pequeñas funciones de puente sin servidor que normalizan el correo entrante y los eventos de ciclo de vida antes de que lleguen a la API.

Esos puentes escriben de vuelta en:

• /ses/webhooks/inbound
• /ses/webhooks/events

Las peticiones incluyen estas cabeceras:

• x-fluxo-timestamp
• x-fluxo-signature
• x-fluxo-event

La firma es un HMAC-SHA256 sobre:

Copiar<timestamp>.<raw-json-body>

No tienes que construir esto tú si usas el módulo de Terraform, pero conviene saberlo para depurar el tráfico de webhooks.

Paso 6: despliega SES sin riesgos

El camino de despliegue limpio es:

1. Deja primero EMAIL_TRANSPORT_PROVIDER=resend.
2. Despliega la infraestructura de SES y verifica el DNS y las identidades.
3. Confirma que los endpoints de webhook de SES son alcanzables desde tu host público de API.
4. Prueba en preproducción el correo saliente, las respuestas entrantes y los eventos de ciclo de vida.
5. Cambia a EMAIL_TRANSPORT_PROVIDER=ses solo cuando SES esté sano.
6. Mantén activo el camino de entrada de Resend durante la ventana de solape para que las cadenas de respuesta antiguas sigan funcionando.

Si haces un despliegue desde cero solo con SES, puedes cambiar directamente a ses en cuanto las identidades, los webhooks y el flujo de entrada estén verificados por completo.

Lista de comprobación

Elijas el proveedor que elijas, comprueba que todo esto funciona:

• un correo transaccional se envía correctamente
• el dominio del remitente está verificado y el proveedor lo acepta
• las respuestas vuelven a la conversación correcta
• los eventos de rebote, queja y fallo llegan a la API y actualizan el estado de supresión
• un evento de entrega es visible en los registros del proveedor (Fluxo no lo guarda)
• los secretos no aparecen en los registros y la retención del correo entrante en bruto coincide con tu política de privacidad

En el caso concreto de SES, confirma además:

• que /ses/webhooks/inbound está recibiendo las cargas normalizadas del puente
• que /ses/webhooks/events está recibiendo eventos de entrega, rebote, queja y fallo; solo el rebote, la queja y el fallo alteran el estado de Fluxo
• que las cadenas de respuesta antiguas de Resend siguen funcionando si migras de forma gradual

Cuándo elegir cada proveedor

Elige resend si quieres:

• el camino de configuración más rápido
• un transporte de correo totalmente alojado
• mantenerte alineado con la configuración por defecto de la aplicación

Elige ses si quieres:

• el stack de correo en tu propia cuenta de AWS
• una pieza más de infraestructura autoalojable
• respuestas entrantes y eventos de ciclo de vida sin depender a largo plazo de un SaaS de correo aparte

Si tienes dudas, empieza con Resend, mantén limpias las variables de entorno comunes del correo y añade SES cuando estés listo para hacerte cargo tú de la infraestructura.