Pense assim: uma campanha de e-mail marketing é como um panfleto que você imprime e distribui para uma lista inteira. Um envio transacional é como uma carta pessoal que se escreve e se envia no momento exato em que algo acontece — alguém comprou, se cadastrou ou pediu para recuperar a senha.
Neste guia conectamos seu sistema com a arrobaMail para enviar esses e-mails automáticos. É um tutorial técnico (você vai ver código), mas está explicado para que qualquer pessoa entenda o que cada passo faz. Se você lida um pouco com HTTP, numa tarde já está funcionando.
Antes de começar
- Uma conta arrobaMail com um remetente verificado (SPF/DKIM) e uma lista.
- Acesso ao backend do seu sistema (ou seu desenvolvedor), para fazer chamadas HTTP.
- Seu usuário e senha da arrobaMail para gerar o token da API.
Os 7 passos
- 1
O que é um envio transacional
Um e-mail individual e automático que responde a um evento pontual, não a uma lista.
- 2
As três formas de enviá-los
API direta, automação por evento ou webhooks: muda quem monta o e-mail e quem dispara.
- 3
Forma 1 — API direta
Seu sistema monta o HTML e envia para a arrobaMail entregar.
- 4
Forma 2 — Automação por evento
O e-mail vive na arrobaMail; seu sistema só registra o evento que dispara.
- 5
Forma 3 — Webhooks
Ao contrário: a arrobaMail avisa seu sistema quando um fluxo chega a um nó Webhook.
- 6
Erros comuns e como resolvê-los
Os tropeços típicos: o evento que não foi salvo, o 404, o token expirado.
- 7
Referência e por onde seguir
O resumo dos endpoints e os lugares para se aprofundar.
1. O que é um envio transacional
Um transacional é um e-mail individual e automático que responde a um evento pontual. Não é enviado para uma lista: tem um destinatário específico e um momento exato. Os do dia a dia:
- Confirmação de compra — "Seu pedido #12345 foi confirmado. Chega na terça-feira."
- Código de verificação (OTP) — "Seu código é 482931. Expira em 5 minutos."
- Nota fiscal eletrônica — "Segue anexa sua nota fiscal de R$ 53,30."
- Lembrete — "Seu horário é amanhã às 10h."
Um esclarecimento importante: a arrobaMail não substitui seu sistema. Seu sistema continua sendo quem detecta o evento. A arrobaMail é o serviço especializado de entrega: recebe a instrução e envia o e-mail com autenticação SPF/DKIM, controle de rejeições e otimização por provedor (Gmail, Outlook, Yahoo). Você cuida do "quando"; a arrobaMail, de "fazer chegar".
2. As três formas de enviá-los
A arrobaMail oferece três mecanismos. O que muda entre eles é quem monta o e-mail e em que direção vai a conversa:
API direta
monta e envia o email
Seu sistema monta o HTML do email e o envia para o arrobaMail entregar.
- Monta o email:
- Seu sistema
- Quando usar:
- O conteúdo é gerado no seu backend: faturas, relatórios com dados variáveis.
Automação por evento
registra um evento
O email já está pronto no arrobaMail; seu sistema só dispara o evento e o arrobaMail envia.
- Monta o email:
- arrobaMail
- Quando usar:
- O email já está desenhado (no editor ou com IA). Seu sistema só diz «envia».
Webhooks
POST para seu servidor
Ao contrário: o arrobaMail avisa seu sistema com um POST quando o fluxo passa pelo nó Webhook.
- Monta o email:
- —
- Quando usar:
- Você precisa que o arrobaMail notifique seu backend quando um fluxo é executado.
Resumindo: se o conteúdo é gerado no seu backend (uma nota fiscal com dados variáveis), API direta. Se o e-mail já está desenhado dentro da arrobaMail e seu sistema só dispara, automação por evento. E se você precisa que a arrobaMail avise seu sistema quando algo acontece, webhooks. Vamos ver as três.
3. Forma 1 — API direta
Seu código monta o e-mail completo (HTML, assunto, remetente) e envia para a arrobaMail. Não há automação: seu sistema decide tudo.
Passo 1 — Obtenha o token JWT. É um passe temporário que autoriza suas chamadas.
POST https://envios.arrobamail.com/v3/api/auth/getToken
Content-Type: application/json
{ "username": "seu_usuario", "pass": "sua_senha", "rememberMe": false, "locale": "pt" }
Você recebe { "token": "eyJhbGci...", "expires": ... }. Guarde-o: ele vai no header Authorization: Bearer {token} de todas as chamadas seguintes.
Passo 2 — Teste com um envio de prova (não consome cota): mande uma cópia para sua caixa para ver como fica.
POST /campaigns/test
Authorization: Bearer {token}
{ "email": "[email protected]", "subject": "Confirmação #12345",
"html": "<html>...</html>", "fromname": "Sua Empresa", "frommail": "[email protected]" }
Passo 3 — Envie o e-mail real. Coloca a entrega imediata na fila.
POST /campaigns
Authorization: Bearer {token}
{ "campname": "Confirmacao_12345", "asunto": "Seu pedido foi confirmado",
"html": "<html>...</html>", "fromname": "Sua Empresa", "frommail": "[email protected]",
"listid": ["SEU_LIST_ID"], "preheader": "Obrigado pela sua compra.",
"tracklinks": 1, "trackreads": 1 }
Você recebe um encid (o identificador da campanha). Guarde-o.
Passo 4 — Consulte o resultado com esse encid:
GET /campaigns/{encid}/stats/subscriber-actions
Isso mostra se o e-mail foi entregue, aberto, se houve cliques e se rejeitou (bounce).
Quando usar: o conteúdo é gerado no seu backend com dados variáveis — notas fiscais, relatórios, comprovantes. Seu código tem controle total sobre o HTML.
4. Forma 2 — Automação por evento
Aqui o e-mail já vive montado dentro da arrobaMail. Seu sistema só diz "envie para essa pessoa agora". A arrobaMail busca a automação, substitui as variáveis e envia. Tem duas partes.
Parte A — Configurar na plataforma (uma única vez)
- Crie a automação: Automação › Nova Automação.
- Escolha o gatilho «Evento personalizado» (é o que responde a chamadas externas).
- Escreva o nome exato do evento — por exemplo,
confirmacao_curso. É sensível a maiúsculas e minúsculas:Confirmacao_Cursonão é a mesma coisa. Verifique que o nome apareça impresso dentro do nó azul. - SALVE. (Sim, em maiúsculas: é o passo que mais se esquece e o que causa a maioria dos problemas.)
- Adicione a ação «Enviar e-mail» abaixo do gatilho e escolha o conteúdo (editor, IA ou template).
- Defina a política de reentrada (o que acontece se o mesmo contato disparar o evento várias vezes): Nunca (boas-vindas), Sempre (faturas, lembretes), Depois de concluir ou Com período de espera.
- Ative o fluxo.
Parte B — Chamar a partir do seu sistema (a cada evento)
Obtenha o token (igual à Forma 1) e depois registre o evento. É um GET com os dados na URL:
GET /events/record?eventName=confirmacao_curso&[email protected]&listid=SEU_LIST_ID&pf_curso=Marketing&pf_fecha=20/06/2026
Authorization: Bearer {token}
O que é cada coisa:
- eventName — o nome exato do gatilho do passo 3 (idêntico, maiúsculas incluídas).
- email — o destinatário; precisa existir como assinante Ativo na lista (se estiver Pendente por double opt-in, não dispara).
- listid — o ID da lista (uma string criptografada, não um número).
- pf_* — variáveis dinâmicas para o e-mail sem salvá-las no contato. No template, são usadas como
{{{pf_curso}}}.
Se a resposta for { "status": "success", ... }, o motor já está processando o evento.
Quando usar: o e-mail já está desenhado na arrobaMail (com o editor ou com IA) e seu sistema só precisa disparar. Menos código do seu lado.
5. Forma 3 — Webhooks
Nas duas formas anteriores, seu sistema fala com a arrobaMail. Esta é ao contrário: quando um assinante passa por um nó Webhook dentro de uma automação, a arrobaMail faz um POST para uma URL sua com os dados do contato. Serve para que a arrobaMail dispare lógica no seu backend (liberar um acesso, emitir uma nota fiscal).
- Crie a automação com gatilho «Evento personalizado» (igual à Forma 2), mas em vez de «Enviar e-mail», adicione um nó de ação Webhook.
- Configure a URL do seu servidor (precisa ser HTTPS).
- Programe o receptor: seu servidor escuta o
POST, lê o JSON e respondeHTTP 200.
<?php // webhook-handler.php
$payload = json_decode(file_get_contents("php://input"), true);
if (isset($payload["email"])) {
$email = $payload["email"];
// Sua lógica aqui: liberar acesso, emitir nota fiscal, etc.
}
http_response_code(200);
echo json_encode(["status" => "ok"]);
Dica: a estrutura do payload pode variar. Nos primeiros testes, registre o body completo para ver exatamente quais campos chegam antes de programar sua lógica.
6. Erros comuns e como resolvê-los
- O evento é registrado mas o e-mail não chega. Quase sempre: o nome do evento não foi salvo no nó. O fluxo mostra "Ativo" mas o gatilho está vazio. → Edite o fluxo, reescreva o nome, verifique que aparece dentro do nó azul e SALVE.
- HTTP 404 — subscriber_not_found. O
emailnão existe como assinante ativo nessalistid. → Cadastre-o antes de chamar o evento (e confira que não está Pendente). - HTTP 401 — token inválido ou expirado. → Peça um novo token e confira que o header diz exatamente
Authorization: Bearer {token}(com o espaço depois de Bearer). - O e-mail chega várias vezes. → Há fluxos duplicados com o mesmo evento, ou a política de reentrada está em "Sempre" e seu código chama a mais. Pause os duplicados e revise seu código.
7. Referência e por onde seguir
Os endpoints que você usou, resumidos:
| Endpoint | Para quê |
|---|---|
POST /auth/getToken |
Obter o token de autenticação. |
POST /campaigns/test |
Enviar um e-mail de teste (API direta). |
POST /campaigns |
Enviar o e-mail real (API direta). |
GET /events/record |
Registrar um evento e disparar a automação. |
GET /campaigns/:encid/stats/subscriber-actions |
Ver se um e-mail foi entregue ou aberto. |
Para o detalhe completo de cada endpoint — parâmetros, respostas e exemplos em curl, Node, PHP e Python — está a referência da API. Para o panorama de todas as formas de integrar (incluindo a IA por MCP), conectar a arrobaMail aos seus sistemas e a página de API.
Próximos passos
- Veja o panorama completo de integração em conectar a arrobaMail aos seus sistemas.
- Aprofunde-se em cada endpoint na referência da API.
- Se quiser operar sua conta com um assistente de IA, veja MCP.