Dispare automações a partir do seu sistema: cadastro por API e evento personalizado

Quando o cadastro dos contatos é feito pelo seu próprio sistema — seu site, seu back-office, sua loja — o gatilho «Inscrição» pode nunca enxergar isso, porque ele espera um opt-in que o seu backend não produz. A solução determinística é o evento personalizado: seu sistema avisa ao arrobaMail "isto aconteceu" com uma chamada HTTP, e o fluxo começa. Na prática é um gatilho no estilo webhook: qualquer sistema, com uma única chamada, pode iniciar uma automação.

Um exemplo para nos situar. No seu e-commerce uma compra é concluída. Você pega esse pedido e, pela API, cadastra o cliente em uma lista com o nome, o email e a categoria do produto. Em seguida registra um evento que dispara a automação: sai um primeiro email de agradecimento com produtos relacionados e, uma semana depois, um segundo com novidades dessa mesma categoria. É isso que você vai montar aqui.

1. Por que um evento personalizado e não «Inscrição»

O gatilho «Inscrição» dispara com o opt-in de um formulário: a pessoa se inscreve, confirma, e só então o fluxo começa. É o caminho certo quando o cadastro entra por um formulário público, e explicamos passo a passo em automatize suas boas-vindas a partir de um formulário.

Mas se o seu cadastro pula essa etapa — porque você o faz pela API, a partir de um back-office, ou com um formulário próprio que confirma em silêncio — o evento de inscrição "visível" nunca acontece, e o fluxo fica esperando algo que não vai chegar. O pior é que não há erro em lugar nenhum: o contato fica perfeito na lista, a automação aparece como ativa, e simplesmente ninguém entra.

O evento personalizado não depende de nada disso. É um sinal explícito que você dispara quando quiser, com o nome que você escolher. Determinístico e sob seu controle.

2. Crie a automação com o gatilho «Evento personalizado»

No editor de automação, abra a categoria Gatilhos da paleta. Está lá, no fim da lista: Evento personalizado.

Arraste-o para a tela e abra a configuração. Ele tem dois campos:

• Nome do evento. Defina um fixo, sem espaços e em minúsculas, no estilo compra_confirmada, cadastro_backoffice ou trial_expirado. Esse nome é o contrato com o seu sistema: tem que coincidir exatamente com o que você disparar, maiúsculas incluídas. O painel sugere exemplos (purchase, signup, lead, view_product, cart_abandoned, trial_started, trial_expired, plan_changed) que funcionam bem como convenção.
• Valor (opcional). Um filtro fino: se você preencher, o fluxo só começa quando o evento chega com aquele valor. Serve para ter um mesmo evento plan_changed disparando fluxos diferentes conforme o plano.

Esse detalhe economiza tempo e erros: você não precisa construir a URL à mão. Copia do painel e só substitui os dois marcadores entre colchetes.

3. O requisito-chave: o contato já precisa estar na lista

Aqui está o ponto em que todo mundo tropeça na primeira vez: o evento dispara, não cria. A automação precisa que o assinante já exista na lista para poder inscrevê-lo no fluxo.

Não é uma contradição nem uma limitação estranha: é separação de responsabilidades. Seu sistema é o dono do dado do contato (cadastra com os campos dele), e o arrobaMail é o dono da conversa (decide qual mensagem sai e quando). O evento é apenas a campainha que conecta os dois.

No fluxo real isso se resolve sozinho, porque o cadastro acontece naturalmente antes: primeiro você registra o cliente, depois avisa que ele comprou.

4. Registre o evento a partir do seu sistema

Quando acontece o fato que te interessa, seu backend chama o endpoint de eventos. Esta é a forma que o painel entrega:

GET /v3/api/events/record?eventName=compra_confirmada&email=[SUBSCRIBER_EMAIL]&listid=[LIST_ID]

Os parâmetros:

• eventName — o nome exato que você configurou no passo 2. Se não coincidir caractere por caractere, não dispara.
• email — o endereço do contato que já está na lista. Substitua o marcador [SUBSCRIBER_EMAIL].
• listid — o identificador da lista. Você o tem no painel; substitua [LIST_ID].
• eventValue (opcional) — só se você configurou o filtro por valor.
• pf_* (opcionais) — campos temporários que viajam com o evento e podem ser usados dentro do email sem salvá-los no contato: pf_order_id, pf_total, pf_categoria. No modelo se escrevem como {{{$pf_order_id}}}, com o $ na frente, igual às variáveis do assinante.

Um exemplo completo com curl, contra a conta de teste gratuita:

curl -G "https://demo.arrobamail.com/v3/api/events/record" \
  --data-urlencode "eventName=compra_confirmada" \
  --data-urlencode "[email protected]" \
  --data-urlencode "listid=SEU_LIST_ID" \
  --data-urlencode "pf_order_id=ORD-123" \
  --data-urlencode "pf_total=99.90"

O domínio é o da sua conta. No exemplo usamos demo.arrobamail.com, que é onde qualquer pessoa pode testar o arrobaMail de graça. Se a sua conta estiver em outro servidor, a URL que você copia do painel já vem com o seu. A base geral da API está documentada no quickstart da API v3.

Alternativa para testar rápido. Existe também uma via legada, POST /eventRecord.php, ainda em serviço, que aceita os mesmos parâmetros no corpo do request. Ela tem uma vantagem concreta para testes e para produção: por ir via POST, o email não viaja na URL. O endpoint documentado, e o que o painel monta, é o GET /v3/api/events/record; se manter os endereços fora dos logs for importante para você, o POST legado é uma opção válida.

5. Respeite a ordem: primeiro o cadastro, depois o evento

Do ponto 3 decorre a regra operacional mais importante deste tutorial. A sequência completa, a partir do seu backend, é esta:

Se o evento chegasse antes do cadastro, não encontra o contato e não dispara — e, de novo, sem erro visível. Como o cadastro acontece primeiro por natureza, a ordem natural já é a correta: garanta apenas que seu código não dispare as duas em paralelo, porque aí sim elas podem se cruzar.

Com o gatilho conectado, o lado arrobaMail do fluxo fica assim:

Repare no que a sua equipe ganha: o conteúdo e os tempos vivem no arrobaMail. Se amanhã você quiser somar um terceiro email, esticar a espera de 7 para 10 dias ou mudar o texto, faz isso pelo editor visual, sem tocar em uma linha do seu sistema nem publicar nada de novo.

6. Ative e verifique a inscrição no fluxo

Salve e ative a automação — como em qualquer fluxo, em rascunho ela não processa ninguém.

Para o teste, faça em três tempos e sem adivinhar:

1. Confirme que seu contato de teste está na lista (olhe no painel, não presuma).
2. Anote a contagem de inscritos atual da automação.
3. Registre o evento para esse email e confira a contagem de novo.

Se o número subiu, o sinal chegou e engatou. Se não subiu, o problema está em um de três lugares, sempre nesta ordem de probabilidade: o nome do evento não coincide exatamente, o contato não estava na lista, ou o listid é de outra lista.

7. Segurança: chame a partir do backend

Duas recomendações para produção, por ordem de importância.

Faça a chamada a partir do seu servidor, nunca do navegador do visitante. É o que mais importa. Se o disparo sair do front, qualquer pessoa pode abrir as ferramentas de desenvolvimento, ver a URL completa — com o seu listid incluído — e começar a iniciar fluxos para endereços arbitrários. Não exponha o listid em páginas públicas.

Tenha em mente que um GET deixa rastro. Com GET, o email viaja na URL e acaba nos logs do servidor, no histórico e nos cabeçalhos Referer. A partir do backend isso é bem menos grave — não há navegador nem referer no meio —, mas se você lida com dados sensíveis ou tem uma política estrita de retenção de logs, a via POST /eventRecord.php do passo 4 mantém o email fora da URL.

Em resumo: chamada do lado do servidor e, se o seu contexto pedir, POST. Com isso o disparo fica seguro, privado e sob seu controle.

Os três gatilhos que iniciam uma conversa

Este tutorial cobre o mais flexível dos três, mas vale ter todos na cabeça: escolher bem o gatilho é 80% do trabalho de uma automação.

Gatilho	Dispara quando…	Ideal para	Guia
Inscrição	alguém confirma o cadastro em uma lista	boas-vindas a partir de um formulário do seu site	boas-vindas por formulário
Evento personalizado	seu sistema registra um evento pela API	compras, cadastros pelo seu backend, qualquer ação da sua plataforma	este guia
Abertura / Clique em email	um contato abre ou clica em uma campanha	acompanhamento por interesse, reenvios, reativação	automatizar por comportamento

A referência completa está em gatilhos de automação.

Erros frequentes a evitar

• Um nome de evento que "quase" coincide. Compra_Confirmada não é compra_confirmada. Defina o nome uma vez, em minúsculas, e copie de um lado para o outro.
• Disparar o cadastro e o evento em paralelo. Parecem duas chamadas independentes, mas a segunda depende da primeira. Encadeie-as.
• Disparar do navegador. Cômodo para testar, indefensável em produção.
• Um evento genérico para tudo. Se signup dispara cinco fluxos diferentes, em três meses ninguém sabe qual faz o quê. Um evento por intenção, e o campo valor para as variantes.
• Esquecer de ativar o fluxo. Vale para todas as automações e segue sendo a causa número um do "não funciona".

Próximos passos

1. Revise o detalhe de cada gatilho em gatilhos de automação.
2. Se você também quiser que o arrobaMail avise o seu sistema quando algo acontece, o caminho inverso são os webhooks de eventos ao vivo.
3. Para confirmações, códigos e faturas que o seu backend monta, veja as três formas de enviar emails transacionais.
4. E para que o fluxo também reaja ao que cada contato faz, siga com aberturas e cliques.