E-mail transacional pelo seu domínio: verificação, eventos e supressão

Código de login, recibo de compra e aviso de redefinição de senha são e-mails que o usuário espera receber na hora. Se eles caem no spam, o cadastro trava, a compra parece não ter sido confirmada e o suporte recebe a reclamação. O e-mail transacional pelo seu domínio resolve isso de forma previsível: o remetente é a sua marca, a autenticação é feita pelo seu DNS, e cada mensagem deixa um registro do que aconteceu com ela.

Por que o remetente precisa ser o seu domínio

Um e-mail enviado a partir de @gmail.com ou de um endereço genérico não tem como provar que veio do seu produto. Os provedores de caixa de entrada olham três coisas: se a mensagem está assinada pelo domínio de origem (DKIM), se o servidor que enviou está autorizado a usar esse domínio (SPF), e se o histórico de envio desse remetente é limpo. O domínio verificado responde às duas primeiras perguntas. A terceira depende de você mandar só para quem espera o e-mail.

Os registros que você precisa criar

Ao cadastrar um domínio, o Messages devolve os registros que devem ir para o DNS dele. São cinco registros, distribuídos em quatro papéis (DKIM, SPF, MX e DMARC):

Os registros de SPF e MX ficam em send.<domínio>, e não na raiz. Essa separação é deliberada: se fossem na raiz, sobrescreveriam o SPF que a sua empresa já usa para o e-mail de hoje, e o e-mail que ela manda sem o Messages quebraria. Com o subdomínio, o seu e-mail atual continua do jeito que está.

A propagação do DNS leva de minutos a algumas horas. Depois de criar os registros, a verificação consulta a AWS na hora em que você pede:

curl -X POST https://messages.worker.myinfrastructure.click/projects/<projectId>/domains/<domainId>/verify \
  -H "Authorization: Bearer msk_..."

Enquanto o status não for verified, o Messages recusa qualquer envio com esse remetente antes de chamar o provedor de envio. Isso evita que o e-mail saia, falhe na autenticação e some sem explicação.

Evento por evento: o log do envio

Cada envio deixa uma linha do tempo. A mensagem aparece como sent quando sai, e depois acumula o que o provedor de caixa de entrada informa: delivered quando chega, opened e clicked quando o destinatário interage, bounced quando é devolvido, complained quando alguém marca como spam.

Isso muda a forma de investigar um problema. Em vez de perguntar ao suporte "você recebeu o código?", a pessoa que opera o produto consulta o envio pelo identificador e vê onde ele parou:

curl https://messages.worker.myinfrastructure.click/emails/<id> \
  -H "Authorization: Bearer msk_..."

A resposta traz o corpo da mensagem e a lista de eventos. Se o último evento for bounced, o provedor de destino recusou a mensagem, e o motivo está no próprio evento. Se não houver delivered depois de um tempo razoável, o problema está do lado do destino. Os números agregados por período estão em GET /metrics.

Supressão automática: não insistir onde não vai chegar

Insistir num endereço que devolveu a mensagem de forma permanente só piora a reputação do seu remetente. O Messages mantém uma lista de supressão por projeto. Quando há uma devolução permanente ou uma reclamação de spam, o endereço entra na lista sozinho, e qualquer envio para ele é recusado antes de sair.

A lista vale só para o projeto em que o endereço foi bloqueado. Se você tiver outro produto com outro domínio, ele não herda essa decisão. Para liberar um endereço, por exemplo depois de uma correção de digitação, use DELETE /suppressions/<email> com uma chave de permissão full.

Envio idempotente: um código, um e-mail

Um código de login enviado duas vezes por um erro de rede é um incômodo pequeno. Um recibo enviado duas vezes é algo que o cliente percebe. Por isso, o POST /emails aceita uma chave de idempotência, no corpo ou no header Idempotency-Key:

{
  "from": "oi@suaempresa.com.br",
  "to": "cliente@exemplo.com",
  "subject": "Seu recibo",
  "html": "<p>Obrigado pela compra.</p>",
  "idempotencyKey": "recibo/pedido-abc"
}

Repetir a chamada com a mesma chave devolve o envio original, com deduplicated: true, e nenhum e-mail novo sai. Uma chamada que falhou não consome a chave, então tentar de novo é seguro. Vale derivar a chave do fato (o pedido, o usuário, a ação) e não do horário.

Caixas de entrada: receber e responder no mesmo lugar

O envio é metade da conversa. Quando o cliente responde o recibo ou pergunta sobre o código, a resposta costuma cair numa caixa que ninguém lê. As caixas de entrada do Messages resolvem isso em duas etapas.

Primeiro, você cria uma caixa com um nome, por exemplo suporte, e ela já recebe e-mail num endereço do Messages. Você não precisa mexer no DNS para começar a receber. Depois, configura o encaminhamento do e-mail que o cliente já usa para esse endereço. As mensagens recebidas viram conversas, agrupadas por assunto, e o evento email.received avisa o seu sistema para tratar cada uma.

A resposta sai pelo seu domínio verificado, com o nome da caixa, e por isso chega na mesma conversa do outro lado. Ela passa pelos mesmos controles de cota, supressão e plano que qualquer envio. A conversa fica ligada pelos cabeçalhos In-Reply-To e References, então a resposta do cliente cai na mesma conversa.

Um cuidado: o encaminhamento leva o que chega à caixa, não o que sai dela pelo Gmail ou outro programa. Se alguém responder direto pelo programa de e-mail, essa resposta não aparece no histórico do Messages. Quem atende pelo painel ou pela API mantém a conversa completa.

Perguntas frequentes

Preciso de um domínio dedicado só para o envio?

Não é obrigatório, e o próprio desenho usa um subdomínio send. para isolar o que o Messages gerencia do restante do seu DNS. O domínio principal continua sendo o da sua marca, que é o que aparece no From.

Posso ter mais de um domínio no mesmo projeto?

Sim, desde que cada domínio seja verificado separadamente. Um envio só passa se o domínio do from estiver verificado no projeto que faz a chamada.

O que acontece se a verificação ficar pendente por dias?

Os envios continuam recusados até o status virar verified. Confira se os cinco registros estão no DNS, com os valores exatos, e tente verificar de novo. Um caractere a mais no CNAME do DKIM impede a conclusão sem mostrar erro, só deixando o status pendente.

Vou perder o histórico se o envio for antigo?

Os envios, eventos e métricas podem ser consultados por uma janela de até 90 dias. O limite é da janela de consulta: não há rotina programada que apague o histórico antigo.

Para continuar lendo

• Login sem senha com código no e-mail: como funciona e quando usar

• Como cobrar assinatura no seu app sem escrever webhook

• Como monitorar o site e ter uma página de status pública

Quando o e-mail é a última etapa

Se o seu produto manda código de acesso, recibo ou aviso de uma ação, vale usar um envio que deixa rastro: domínio verificado, evento por evento e supressão automática. O Messages entrega isso para o envio transacional, e as caixas de entrada cobrem a resposta, sem exigir que você monte um sistema de suporte por e-mail do zero.

Fontes

• Referência do Messages para pessoas e agentes (llms.txt)

• Página do Messages