Overview
Mensagens
Seção intitulada “Mensagens”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:
- uma chave de API — ver Chaves de API;
- um domínio de envio cadastrado e com o DNS confirmado, no painel do SMTP;
- 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
POST /messagesdevolve 202 com omessage.tracking_code;- guarde esse código junto do seu pedido, do seu usuário, do que fizer sentido;
- 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.
