Envío fiable de correo transaccional: fila outbox, worker, reintentos y claves de idempotencia

Objetivo

Cada confirmación de pedido, restablecimiento de contraseña o factura sale del sistema una sola vez, sobrevive a caídas de procesos y a interrupciones del proveedor, y se puede rastrear desde el evento de negocio hasta el identificador de mensaje del proveedor.

Requisitos previos

Un almacén duradero (basta la propia base de datos de la aplicación), un proceso worker, un proveedor o un MTA accesible por SMTP o HTTP, y una convención para el Message-ID. El RFC 5321, citado aquí, divide las respuestas negativas en transitorias (4yz: la misma petición puede funcionar más adelante) y permanentes (5yz: no se debe repetir la petición sin cambios); el RFC 5322, también citado, exige que el Message-ID sea un identificador globalmente único.

Pasos

1. En la misma transacción de base de datos que registra el evento de negocio, inserta una fila outgoing_email con: destinatario, nombre de la plantilla, parámetros ya preparados para el renderizado, una clave de idempotencia derivada del evento (order-1234-confirmation), un Message-ID recién generado y el estado pending. Es el patrón outbox aplicado al correo.
2. Un worker reclama un lote de filas pendientes (en PostgreSQL: SELECT ... FOR UPDATE SKIP LOCKED), renderiza el mensaje y llama al proveedor con el Message-ID almacenado y, si la API admite una, con la clave de idempotencia.
3. Clasifica el resultado. Las respuestas 4yz, los errores de conexión y los timeouts admiten reintento: conserva la fila, incrementa attempts y fija next_attempt_at con backoff exponencial y jitter. Las respuestas 5yz y las direcciones rechazadas son definitivas: marca la fila como failed con el texto de la respuesta y no sigas.
4. Limita los intentos y la antigüedad. El RFC 5321 indica que el tiempo tras el cual un MTA se rinde suele tener que ser de al menos 4-5 días; una cola de aplicación suele fijar un límite mucho antes, y las filas que lo superan pasan a un estado de dead-letter que dispara una alerta.
5. Guarda en la fila el identificador de mensaje del proveedor y las marcas de tiempo, de modo que los rebotes, las quejas y las consultas de soporte puedan vincularse de nuevo con el evento.
6. Haz que el worker sea seguro al ejecutarse en paralelo y tras caídas: la clave de idempotencia única o el Message-ID es lo que impide un segundo envío cuando el proceso muere entre «el proveedor aceptó» y «fila marcada como enviada».
7. Usa colas o prioridades separadas para el correo sensible al tiempo (códigos de inicio de sesión, restablecimientos) y para todo lo demás, de modo que una ráfaga de envíos masivos no retrase un código.

Resultado esperado

Los envíos sobreviven a los reinicios; una interrupción del proveedor se manifiesta como un aumento del número de pendientes y no como correo perdido; los duplicados tras una caída se evitan gracias a la clave y no por suerte.

Límites y base de verificación

«Exactamente una vez» solo se cumple hasta donde llega la API del proveedor: un proveedor que aceptó la petición pero nunca respondió puede haber enviado el mensaje igualmente, y las claves de idempotencia del lado del proveedor normalmente se respetan solo durante un periodo que el proveedor documenta. Prueba matando el worker entre el envío y el marcado como enviado, y simulando respuestas 4yz y 5yz. Basado en los RFC citados y en prácticas documentadas; no se afirma ningún dato de tiempos ni de tasas.