Pular para o conteúdo

Overview

Enviar e-mail e SMS, e saber o que aconteceu com cada mensagem.

Um endpoint para os dois canais: POST /messages, com channel decidindo — e o padrão é email.

Antes da primeira chamada

Três coisas, todas no painel:

  1. uma chave de API — ver Chaves de API;
  2. um domínio de envio cadastrado e com o DNS confirmado, no painel do SMTP;
  3. ao menos uma conta de envio nesse domínio — é ela que autentica a mensagem.

⚠️ O from pode ser qualquer endereço de um domínio seu, como no Resend e no SES: {seller}@seudominio.com.br serve sem cadastrar cada endereço. Domínio que não é seu devolve 422 — sem ele cadastrado não há assinatura DKIM, e a mensagem cai em spam ou é recusada pelo destino. Subdomínio é cadastrado como domínio próprio: mail.seudominio.com.br não herda o cadastro de seudominio.com.br.

Quem autentica é uma conta de envio do domínio do from: a do próprio from, quando ele é uma conta; senão, a conta mais antiga do domínio. Para escolher, informe from_auth. É essa conta que aparece em message.smtp_account_id e no painel do SMTP; o from continua sendo o endereço que você mandou.

O caminho

  1. POST /messages devolve 202 com o message.tracking_code;
  2. guarde esse código junto do seu pedido, do seu usuário, do que fizer sentido;
  3. para saber o desfecho: GET /messages/{tracking_code} ou receba o evento de webhook, que entrega o mesmo objeto.

⚠️ 202 quer dizer “aceita”, não “entregue”. A mensagem entrou na fila e sai em seguida; 200 daria a impressão errada.

⚠️ Guarde o tracking_code, não o message.id. Poucos minutos depois de terminar, a mensagem é arquivada e o identificador interno muda. O código de rastreio resolve nos dois momentos, e é ele que chega em todo evento.

O vocabulário de delivery.status

msg:yes:queue aceita, na fila de envio
msg:yes:queue:job em transmissão para o nosso servidor de envio
msg:yes:delivered o nosso servidor de envio aceitou; o resultado no destino ainda não chegou
msg:yes:finished arquivada sem falha registrada — confira delivery.recipients, onde um kind unknown não muda o status
msg:yes:finished:with:bounce arquivada: ao menos um destinatário com bounce — ver delivery.recipients
msg:yes:finished:with:filter arquivada: ao menos um destinatário descartado, pelo destino ou por regra da plataforma
msg:yes:finished:with:trap reservado: o envio ainda não identifica armadilha de spam, e nenhuma mensagem recebe este status hoje
msg:not:undelivered não saiu da plataforma — delivery.bounce traz o código e a frase quando foi um servidor que recusou; é nulo quando a causa foi a credencial, o remetente, o destinatário ou uma falha nossa
msg:not:undelivered:trashed venceu o prazo na fila antes de sair

⚠️ Falha no destino aparece como msg:yes:finished:with:*, não como msg:not:*. A mensagem saiu e o ciclo terminou; quem não recebeu está em delivery.recipients. Com mais de um tipo de falha, vale o mais grave: filter, depois bounce (e trap antes dos dois, quando existir). Trate o prefixo msg:yes:finished como “terminou” e leia o resto como o resumo.

O resultado por destinatário: delivery.recipients

Na consulta de uma mensagem e nos eventos de webhook do arquivamento — nunca antes dele. Um item por endereço, entregue ou não:

campo
kind null (entregue), hard, soft, discarded ou unknown (o registro do envio não permite classificar — trate como falha sem causa conhecida); trap é reservado e não ocorre hoje
code, answer o que o servidor de destino respondeu, sempre que foi ele quem falou
discard_reason só quando fomos nós que descartamos antes de discar: score_below_minimum, score_below_destination, missing_spf, suppressed, unknown

⚠️ discarded cobre dois casos: o destino recusou antes de enfileirar (um 554 de conteúdo, por exemplo — aí answer traz a frase dele) e a plataforma descartou por regra sua (aí discard_reason diz qual). Os dois contam em delivery.discarded.

Medição de abertura e clique

Desligada por padrão: sem o campo tracking, o HTML que você manda é o que o destinatário recebe. Para medir, peça no envio:

tracking.clicks troca cada link http/https no href de um link — <a>, <area> ou o botão VML do Outlook —, entre aspas duplas ou simples, no html por um endereço de redirecionamento no seu domínio de rastreio; o endereço final ganha utm_source, utm_medium e utm_term, antes do #
tracking.opens acrescenta uma imagem de rastreamento (o pixel) ao fim do html

Cada abertura e cada clique chega pelo webhook, como email.opened e email.clicked.

O link reescrito não expira. Depois de 7 dias a mensagem sai da retenção: o clique continua levando ao seu endereço, e só deixa de ser contado.

⚠️ Só há reescrita com o rastreamento do domínio confirmado. O domínio do from precisa do CNAME track-s1 publicado e verificado no painel do SMTP — ver Publicar os registros DNS do domínio. Sem ele, o envio é aceito com 202, os links saem como você escreveu e nada é medido: reescrever para um endereço que ainda não responde deixaria o destinatário sem o link.

⚠️ O text não é alterado, nem o endereço escrito por extenso no corpo do HTML. No canal SMS o campo é recusado com 422.

O que este recurso NÃO faz

  • não tem template nem agendamento — o corpo vai pronto no pedido, e o envio é imediato;
  • não substitui variáveis por destinatário — um pedido é uma mensagem.

Vindo de outro provedor? A equivalência campo a campo está em Migrar o envio de e-mail.