Pular para o conteúdo
~/rafael-ferreira

E-mail marketing com domínio próprio (BYOD) e Amazon SES

Como cada clínica do Markmedi envia campanhas pelo próprio domínio, com DKIM alinhado, verificação contínua de DNS, fila isolada e tratamento de bounces via SNS.

8 min de leitura #markmedi #amazon-ses #email #laravel

Quando comecei o módulo de e-mail marketing do Markmedi, a primeira tentação foi a mais simples: mandar tudo de um endereço da plataforma, algo como campanhas@ no nosso domínio, e trocar só o nome de exibição. Funciona no primeiro dia. No terceiro mês, uma clínica que compra lista ou escreve um assunto ruim derruba a reputação do domínio inteiro, e as campanhas de todas as outras clínicas passam a cair no spam. Além disso, a paciente recebe um e-mail da clínica dela vindo de um domínio que ela nunca viu, o que já é meio caminho para o botão "denunciar".

A decisão foi trabalhar com BYOD (bring your own domain): cada clínica envia pelo próprio domínio, com assinatura DKIM própria, e a reputação de uma não contamina a da outra. O preço disso é complexidade operacional, porque agora eu dependo de registros DNS que a clínica (ou o sobrinho que cuida do site dela) precisa configurar e manter. Este artigo é sobre como lidei com isso.

Uma identidade SES por clínica

Cada clínica tem no máximo uma identidade de envio. Quando o administrador informa o domínio, eu normalizo a entrada (tiro esquema, caminho, porta e www.) e chamo a API v2 do SES para criar uma email identity com Easy DKIM de 2048 bits. As chamadas à AWS acontecem fora da transação do banco: não quero segurar um lock enquanto espero a rede.

Junto com a identidade, configuro um MAIL FROM personalizado num subdomínio de envio. Sem isso, o envelope (o Return-Path) sairia com o domínio da Amazon, o SPF ficaria alinhado com a Amazon e não com a clínica, e o DMARC não passaria por SPF. O detalhe que mais importa aqui é o comportamento em falha de MX: configurei como REJECT_MESSAGE. Se o registro MX do subdomínio sumir, prefiro que o SES recuse o envio a cair silenciosamente de volta para o domínio da Amazon e começar a gerar e-mails desalinhados.

O From da clínica se alinha com o DKIM pelos três CNAMEs e com o SPF pelo MAIL FROM próprio, e o DMARC passa

O domínio é único na tabela inteira. Uma clínica não pode registrar o domínio de outra, e isso vale também para a corrida em que duas clínicas cadastram o mesmo domínio no mesmo segundo: a verificação no código pega o caso comum, e a violação do índice único pega o caso raro, que eu traduzo para a mesma mensagem de erro.

Os registros que a clínica precisa criar

A tela de domínio mostra exatamente o que precisa ir para o DNS, com um botão de "copiar tudo" num formato que dá para colar no WhatsApp de quem administra o domínio. Na prática, é este conjunto:

Registro

Onde

Para quê

3 × CNAME

{token}._domainkey

Chaves públicas do Easy DKIM, que a AWS rotaciona sozinha

MX

subdomínio de envio

Recebe os retornos (bounces) do MAIL FROM

TXT (SPF)

subdomínio de envio

Autoriza o SES a enviar pelo envelope da clínica

TXT (DMARC)

_dmarc

Recomendado, não obrigatório para liberar o envio

Coloquei o SPF no subdomínio de envio de propósito. Assim eu não preciso mexer no SPF do domínio raiz da clínica, que muitas vezes já tem o Google Workspace ou outro provedor e um limite de consultas DNS perto do teto.

Verificação como máquina de estados

Uma identidade passa por quatro estados: pending, verified, failed e revoked. Um comando agendado a cada 15 minutos consulta o SES e avança o estado. A janela para a clínica configurar o DNS é de 72 horas; depois disso, ou se o DKIM falhar, a identidade vai para failed.

O ponto que mais me trouxe problema no começo foi assumir que verified era um estado final. Domínio verificado não continua verificado para sempre: alguém troca o provedor de DNS, migra o site, apaga "aqueles registros estranhos" e o envio começa a falhar. Por isso o comando também revisita identidades já verificadas. Se os registros somem, a identidade vai para revoked, as campanhas daquela clínica param de sair, e ela só volta a enviar depois de uma verificação completa de novo. Toda transição relevante notifica os administradores da clínica, com o motivo.

Máquina de estados da identidade: pending vira verified ou failed; verified vira revoked se os registros DNS somem

O pipeline de envio

Uma campanha pode ser disparada de dois lugares: pelo agendador (campanhas programadas) e pelo botão "enviar agora". Para que as duas entradas não disparem a mesma campanha duas vezes, o primeiro passo é um claim atômico: um UPDATE condicional que só muda o status se ele ainda estiver no estado esperado. Quem não conseguiu fazer o claim desiste.

Depois disso eu não carrego a audiência inteira na memória. O despacho percorre os destinatários em lotes de 100 e, para cada um, coloca um job na fila emails. O tamanho do lote também define quão rápido um cancelamento funciona: se a clínica cancela no meio, no máximo um lote já está a caminho. A fila emails tem um supervisor próprio no Horizon, com um único processo, para que uma campanha grande nunca dispute worker com lembretes de consulta. Escrevi mais sobre essa separação em filas com Laravel Horizon.

Cada job de destinatário passa por uma sequência de guardas antes de enviar: destinatário sem e-mail, campanha cancelada, identidade ausente ou não verificada, endereço suprimido (descadastro ou bounce) e quota esgotada. Cada saída antecipada grava uma linha no registro de mensagens com o motivo, e esse registro tem uma chave de idempotência única. Se o job rodar duas vezes, a segunda execução encontra a linha e não envia de novo.

Ida: claim atômico, lotes de 100, fila emails, guardas, rate limit global e SES. Volta: SNS, webhook com três verificações, deduplicação e supressão por clínica

Rate limit global, quota por clínica

O limite de envio do SES é por conta da AWS, não por clínica. Por isso o rate limiter ses-send é global, aplicado como middleware do job. Se eu fizesse um limiter por clínica, dez clínicas enviando ao mesmo tempo estourariam o limite da conta e o SES começaria a recusar.

A quota mensal de cada clínica (que depende do plano) é controlada por um contador numa única linha, incrementado com compare-and-set:

UPDATE email_quota_counters
   SET used = used + 1
 WHERE clinic_id = ? AND period = ? AND used < quota_limit;
-- 1 linha afetada: pode enviar. 0 linhas: quota esgotada.

Não precisa de lock explícito: o próprio UPDATE é atômico. O contador é só um atalho rápido; a fonte da verdade é o registro de mensagens enviadas, e existe uma reconciliação que recalcula o contador a partir dele se os dois divergirem.

Pausa

Uma campanha pausada não pode simplesmente fazer os jobs falharem. O job verifica a pausa, se coloca de volta na fila com um atraso de alguns minutos e estende o próprio prazo de expiração, para que uma pausa longa não transforme todos os envios pendentes em falhas. Jobs de campanha pausada também pulam o rate limiter, para não consumir capacidade de quem está enviando de verdade.

Cabeçalhos que importam

O From sempre usa o domínio verificado da clínica. A campanha pode trocar o nome de exibição e o Reply-To, mas não o domínio do remetente, porque é ele que precisa estar alinhado com o DKIM para o DMARC passar.

Todo e-mail sai com List-Unsubscribe e List-Unsubscribe-Post: List-Unsubscribe=One-Click, o descadastro em um clique da RFC 8058 que o Gmail e o Yahoo passaram a exigir de remetentes em volume. O configuration set do SES é escolhido pela preferência da clínica: com rastreamento de abertura e clique, ou sem. E-mails de teste sempre usam o conjunto sem rastreamento. As message tags carregam só identificadores (clínica e envio), que é o que eu preciso para casar os eventos de volta.

Bounces e reclamações via SNS

O SES publica entregas, bounces, reclamações, aberturas e cliques num tópico SNS, que chama um webhook do Markmedi. Um endpoint público que altera listas de supressão é um alvo óbvio, então ele tem três cercas antes de aceitar qualquer coisa:

  1. O TopicArn precisa estar numa lista de permissão configurada. Lista vazia recusa tudo.
  2. A URL do certificado de assinatura precisa ser de um host SNS da AWS, validada por expressão regular, antes de eu baixar qualquer coisa.
  3. A assinatura é verificada com openssl_verify, nas versões 1 e 2 do SNS. Versão desconhecida é recusada.

A confirmação de inscrição do SNS só é seguida se a URL for da própria AWS, o que evita usar o webhook para fazer o servidor buscar URLs arbitrárias. Cada evento é deduplicado pelo MessageId antes de ir para a fila critical, porque o SNS entrega pelo menos uma vez e às vezes entrega duas.

As regras de supressão são conservadoras: bounce permanente suprime o endereço na hora; bounces temporários suprimem depois de três seguidos desde a última entrega bem-sucedida; reclamação de spam vira descadastro de marketing imediatamente. A supressão é por clínica: o fato de uma paciente se descadastrar da newsletter de uma clínica não diz nada sobre outra.

Descadastro sem armadilha

O link de descadastro é uma rota assinada que não expira, de propósito: um e-mail de seis meses atrás ainda precisa permitir o descadastro. O GET só mostra a página de confirmação e não altera nada, porque antivírus de e-mail e pré-visualizadores abrem links sozinhos e eu não quero descadastrar ninguém por causa de um scanner. A confirmação é um POST, e existe um POST separado para o one-click que o provedor de e-mail chama direto do servidor dele. Há também como desfazer, e a página funciona sem JavaScript.

O que eu faria diferente

Subestimei o suporte. A parte técnica do BYOD é bem documentada; a difícil é a clínica cujo domínio está num painel que ninguém sabe acessar. O formato de "copiar tudo para mandar no WhatsApp" nasceu disso, e vale mais do que qualquer otimização de envio que eu tenha feito.

Esse módulo é uma das peças do Markmedi. A forma como as filas são separadas está em filas com Laravel Horizon, e o isolamento entre clínicas, em multitenancy e segurança.