Envio confiável de e-mail transacional: linha de outbox, worker, novas tentativas e chaves de idempotência

Objetivo

Toda confirmação de pedido, redefinição de senha ou fatura sai do sistema uma única vez, resiste a falhas de processo e a indisponibilidades do provedor e pode ser rastreada desde o evento de negócio até o identificador de mensagem do provedor.

Pré-requisitos

Um armazenamento durável (o próprio banco de dados da aplicação basta), um processo worker, um provedor ou MTA acessível por SMTP ou HTTP e uma convenção para o Message-ID. A RFC 5321, citada aqui, divide as respostas negativas em duas classes: transitórias (4yz: a mesma requisição pode ter sucesso mais tarde) e permanentes (5yz: não repita a requisição sem alterá-la). A RFC 5322, também citada, exige que o Message-ID seja um identificador globalmente único.

Passos

1. Na mesma transação de banco de dados que registra o evento de negócio, insira uma linha outgoing_email com: destinatário, nome do template, parâmetros já renderizados, uma chave de idempotência derivada do evento (order-1234-confirmation), um Message-ID recém-gerado e o status pending. É o padrão outbox aplicado a e-mail.
2. Um worker reserva um lote de linhas pendentes (no PostgreSQL: SELECT ... FOR UPDATE SKIP LOCKED), renderiza a mensagem e chama o provedor com o Message-ID armazenado e, quando a API aceitar, com a chave de idempotência.
3. Classifique o resultado. Respostas 4yz, erros de conexão e timeouts permitem nova tentativa: mantenha a linha, incremente attempts e defina next_attempt_at com backoff exponencial e jitter. Respostas 5yz e endereços rejeitados são definitivos: marque a linha como failed com o texto da resposta e pare.
4. Limite o número de tentativas e a idade da mensagem. A RFC 5321 diz que o tempo até um MTA desistir geralmente precisa ser de pelo menos 4 a 5 dias; uma fila de aplicação costuma limitar bem antes disso, e as linhas que passam do limite vão para um status de dead-letter que dispara um alerta.
5. Guarde na linha o identificador de mensagem do provedor e os timestamps, para que bounces, reclamações e dúvidas do suporte possam ser associados de volta ao evento.
6. Faça o worker seguro para rodar em paralelo e após falhas: a chave de idempotência ou o Message-ID únicos são o que impede um segundo envio quando o processo morre entre "provedor aceitou" e "linha marcada como enviada".
7. Use filas ou prioridades separadas para e-mails urgentes (códigos de login, redefinições) e para todo o resto, de modo que um pico de envio em massa não atrase um código.

Resultado esperado

Os envios sobrevivem a reinicializações; uma indisponibilidade do provedor aparece como um número crescente de pendentes, e não como e-mails perdidos; duplicatas após uma falha são evitadas pela chave, e não por sorte.

Limites e base de verificação

"Exactly once" (exatamente uma vez) vale apenas até o limite da API do provedor: um provedor que aceitou a requisição mas nunca respondeu pode ter enviado a mensagem mesmo assim, e as chaves de idempotência do lado do provedor costumam ser respeitadas apenas durante um período que o próprio provedor documenta. Teste encerrando o worker entre o envio e a marcação como enviado, e simulando respostas 4yz e 5yz. Baseado nas RFCs citadas e em prática documentada; não se afirmam tempos nem taxas.