Referência
Gatilhos de automação
Referência de todos os gatilhos de automação por contexto, com as opções e os filtros deles, o que os dispara e as chaves de gatilho a usar com a API.
Um gatilho decide quando uma automação inicia uma execução. Esta página lista todos os gatilhos disponíveis em cada contexto, o que os dispara, as opções deles e a chave que você usa para cada um na API.
Como os gatilhos funcionam
- Um gatilho por automação no painel. Selecione o gatilho no canvas e altere-o em Trigger type. Pela API, as automações dos contextos Contact e Email podem ter vários gatilhos, desde que todos se conectem à mesma primeira etapa. As automações do contexto Event têm exatamente um. Cada gatilho disparado inicia a própria execução, então um único cadastro pode iniciar duas: um formulário que adiciona o contato a uma lista de contatos dispara Form submitted e Added to audience ao mesmo tempo. Para uma única execução, na aba Settings, defina Same contact again while a run is in progress como Don’t start another run (
allow_reentry: false). - A automação precisa estar em execução. Os gatilhos de automações em rascunho, pausadas ou interrompidas são ignorados. Eventos anteriores ao início de uma automação não iniciam execuções depois.
- As execuções começam em segundos. O Emailit capta os novos eventos a cada poucos segundos. Os gatilhos de data são verificados a cada 5 minutos.
- As automações do contexto Contact precisam de um contato. Um evento que não pode ser associado a um contato do workspace, como uma abertura por um endereço que não é um contato, não inicia uma execução.
- As automações podem iniciar umas às outras. As alterações feitas por uma etapa, como adicionar uma tag ou adicionar um contato a uma lista de contatos, disparam os gatilhos de outras automações. Uma automação nunca inicia a si mesma dessa forma, e uma cadeia de automações que iniciam umas às outras para depois de 5 elos.
Filtros
Contact updated, Custom event, Placed an order, Abandoned a cart, Viewed a product, Product back in stock e todos os gatilhos de e-mail aceitam um filtro opcional. Cada regra compara um campo do evento com um valor:
- Operadores: Equals, Not equals, Contains, Not contains, Greater than, Less than, Is set, Is not set, In, Not in, Starts with e Ends with. Greater than e Less than comparam números. Os demais comparam texto e diferenciam maiúsculas de minúsculas.
- Modo de correspondência: All rules match ou Any rule matches.
Pela API, um filtro é { "match": "all", "rules": [{ "field": "...", "operator": "equals", "value": "..." }] } no config.filter do gatilho, com match definido como all ou any. Os campos são caminhos dentro do objeto do evento, por exemplo to, link.url ou, para um evento personalizado, properties.total. Para verificar o próprio contato (tags, listas de contatos, pontuação), adicione uma etapa Condition depois do gatilho.
Gatilhos de contato
| Gatilho | Chave na API | Opções | Inicia uma execução quando |
|---|---|---|---|
| Added to audience | contact.added_to_audience |
Audience. Deixe vazio para qualquer lista de contatos. | Um contato entra na lista, ou é adicionado de novo depois de se descadastrar. |
| Removed from audience | contact.removed_from_audience |
Audience. Deixe vazio para qualquer lista de contatos. | A participação de um contato na lista é excluída. |
| Added to segment | contact.added_to_segment |
Tracked segment (obrigatório) e se os membros atuais devem ser incluídos | Um contato passa a corresponder a um segmento rastreado. |
| Removed from segment | contact.removed_from_segment |
Tracked segment (obrigatório) | Um contato deixa de corresponder a um segmento rastreado. |
| Contact created | contact.created |
Nenhuma | Um contato é criado. |
| Contact updated | contact.updated |
Field that changed, filtro opcional | Os campos, os campos personalizados, as tags, a pontuação ou o status de marketing de um contato mudam. |
| Tag added | contact.tag_added |
Tag. Deixe vazio para qualquer tag. | O contato recebe a tag. |
| Tag removed | contact.tag_removed |
Tag. Deixe vazio para qualquer tag. | A tag é removida do contato. |
| Score changed | contact.score_changed |
Crosses e Direction | A pontuação de lead do contato muda, ou ultrapassa um limite. |
| Unsubscribed | contact.unsubscribed |
Audience. Deixe vazio para qualquer uma. | O contato se descadastra de uma lista de contatos, ou de todos os e-mails de marketing. |
| Email opened | contact.loaded_email |
Apenas e-mails enviados por esta automação | O contato carrega um e-mail rastreado enviado para o endereço dele. |
| Link clicked | contact.clicked_in_email |
Link contains, apenas e-mails enviados por esta automação | O contato clica em um link rastreado de um e-mail enviado para o endereço dele. |
| Date in contact field | contact.on_date |
Date field, deslocamento, horário, fuso horário, Repeat | Chega uma data armazenada no contato, ou falta um número definido de dias para ela. |
| Date anniversary | contact.date_anniversary |
Date field, deslocamento, horário, fuso horário | Todo ano, no mês e no dia de uma data do contato. |
| Custom event | contact.on_event |
Event name. Deixe vazio para qualquer um. | A sua aplicação envia um evento do workspace ou personalizado para o contato com a API de eventos, como uma compra. Planos Business e Custom. |
| Form submitted | form.submitted |
Form. Deixe vazio para qualquer formulário. | Alguém envia um formulário com um endereço de e-mail. |
| Placed an order | contact.on_purchase |
Filtro opcional | Um contato faz um novo pedido. |
| Abandoned a cart | contact.abandoned_cart |
Filtro opcional | O carrinho de um contato é abandonado. |
| Viewed a product | contact.viewed_product |
Filtro opcional | Um contato vê um produto no seu site. |
| Product back in stock | contact.back_in_stock |
Filtro opcional | Um produto que um contato pediu volta a ficar disponível. |
Added to audience
Dispara quando alguém é adicionado a uma lista de contatos pelo painel (Add subscriber, Add to audience, Add contact com listas), pela API (Adicionar um inscrito, ou Criar um contato com audiences), com a ação em massa Add to audience ou pela etapa Add to audience, Subscribe / unsubscribe ou Create contact de outra automação. Adicionar de novo alguém que se descadastrou também o dispara.
Ele não dispara para contatos adicionados por uma importação de arquivo ou por uma inscrição pela URL de inscrição, e reativar Subscribed para um inscrito existente no painel também não conta.
Removed from audience
Dispara quando um inscrito é excluído: Delete na página da lista, Remove from audience, Excluir um inscrito, uma atualização de contato cuja lista audiences deixa a lista de fora ou a etapa Remove from audience de outra automação. Excluir um contato o dispara uma vez para cada lista em que o contato estava. Descadastrar não o dispara, porque a pessoa continua na lista; para isso, use Unsubscribed.
Para interromper as execuções de uma sequência quando o contato sai da lista dela, você não precisa de uma segunda automação: ative Leave when removed or unsubscribed from the audience that started the run na aba Settings. Consulte Condições de saída e metas.
Gatilhos de segmento
Added to segment e Removed from segment disparam quando um contato entra em um segmento rastreado ou sai dele. Assim como os segmentos, eles estão em alfa e abertos apenas à equipe do Emailit. Escolha o segmento em Tracked segment. Apenas os segmentos rastreados são listados e aceitos, porque os outros segmentos não registram entradas e saídas.
- Quando disparam. Quando um contato muda, os segmentos dele são verificados de novo, e as execuções geralmente começam em até um minuto. Importações e exclusões de listas são verificadas quando terminam. Regras que mudam com o tempo, como Created nos últimos 30 dias, são verificadas por uma sincronização diária às 00:30 UTC.
- Edições no segmento não iniciam execuções. Os contatos que entram ou saem porque você alterou a origem ou os filtros do segmento são registrados e enviados aos webhooks, mas não iniciam automações.
- Nenhuma execução na primeira contagem. Criar um segmento rastreado, ou retomar o rastreamento depois de um upgrade, registra os membros atuais sem iniciar execuções.
- Incluir os membros atuais. Em Added to segment, selecione Also start for contacts already in the segment when the automation is first started para iniciar uma execução também para cada membro atual. Isso acontece uma vez, no primeiro início da automação. As configurações de reentrada continuam valendo.
Em uma execução, {{payload.object.segment.name}} contém o nome do segmento e {{payload.object.reason}}, o motivo pelo qual o contato entrou ou saiu: contact, schedule ou existing_member, para as execuções iniciadas para os membros atuais do segmento.
Pela API, defina config.segment_id com o ID seg_ do segmento e, para contact.added_to_segment, opcionalmente config.include_current_members: true. Um segmento que as automações usam não pode ser excluído até você alterar essas automações.
Contact updated
Dispara sempre que um contato é atualizado no painel, pela API ou por uma etapa de automação, incluindo alterações de tags e de pontuação e as ações em massa Unsubscribe e Resubscribe. Field that changed o restringe a um campo, por exemplo, um campo personalizado purchased que o seu CRM define. O filtro pode verificar os valores atuais de Email, First name, Last name, Unsubscribed e dos campos personalizados, e os valores anteriores deles, listados como Previous email, Previous first name e assim por diante. Os valores anteriores só estão presentes para os campos que mudaram.
Por exemplo, para reagir quando um contato passa para o plano pro, adicione duas regras com All rules match: custom_fields.plan Equals pro e Previous plan (previous.custom_fields.plan) Not equals pro.
Tag added e Tag removed
Disparam quando uma tag é adicionada ao contato ou removida dele por qualquer meio: o painel, a API, o servidor MCP ou uma etapa de automação. As tags são comparadas em minúsculas, então VIP e vip são a mesma tag.
Score changed
Dispara quando a pontuação de lead do contato muda. Com Crosses definido, ele só dispara quando a pontuação passa desse valor: subindo (Going up, o padrão) significa que a pontuação antiga estava abaixo dele e a nova está nele ou acima, então “leads acima de 50 entram no fluxo de vendas” dispara uma vez, e não a cada ponto. Going down dispara quando a pontuação cai abaixo do valor.
Unsubscribed
Dispara quando o contato se descadastra de uma lista de contatos (um link de descadastro, o painel, a API ou uma etapa Subscribe / unsubscribe) ou de todos os e-mails de marketing. Com Audience definido, ele só dispara para essa lista e para descadastros de tudo.
Email opened e Link clicked
Disparam quando o contato carrega um e-mail rastreado enviado para o endereço dele ou clica nele: campanhas, e-mails enviados pela API e por SMTP e e-mails de automações. O rastreamento exige as configurações de rastreamento do domínio de envio e um CNAME de rastreamento verificado. Only emails sent by this automation os restringe aos e-mails da própria automação, e Link contains, aos links cuja URL contém o texto, por exemplo, /pricing.
Para reagir a uma abertura ou a um clique de um e-mail que a execução acabou de enviar, use uma etapa Wait until com Something happens. Consulte Wait until.
Date in contact field e Date anniversary
Escolha um Date field, um campo personalizado do tipo data, como uma data de renovação ou um aniversário, e depois quando começar:
- Days com Unit (
daysouweeks) e When (before the dateouafter the date), por exemplo, 3 dias antes de uma renovação.0significa na própria data. - At time (padrão
00:00) em Timezone (um nome IANA comoEurope/Prague, padrão UTC). - Repeat em Date in contact field: Once, on that date ou Every year (anniversary). Date anniversary sempre se repete todo ano; o ano no campo não importa, então
1990-04-12inicia uma execução todo dia 12 de abril. Nos anos não bissextos, os aniversários de 29 de fevereiro começam em 28 de fevereiro.
O Emailit olha 5 minutos à frente e inicia cada execução no minuto que você definiu. Cada contato recebe uma execução por data (ou por ano, nos aniversários), e cada verificação processa até 100.000 contatos por automação.
Pela API, defina config.date_field como a chave do campo personalizado, offset como { "amount": 3, "unit": "days", "direction": "before" } e, se quiser, time, timezone e repeat: "yearly".
Custom event
Este gatilho está incluído nos planos Business e Custom. No Pay as you go e no Pro, não é possível salvar uma automação que o adiciona (403 com "error": "plan_required"). As automações que já o usam continuam com ele depois de um downgrade.
Dispara quando a sua aplicação envia um evento personalizado (eventos c:) ou um evento do workspace (eventos w:) para o contato com a API de eventos. Os eventos do script de rastreamento não iniciam execuções, porque qualquer pessoa com a sua chave de rastreamento pública pode atribuir uma identidade a qualquer visitante. Informe o nome em Event name:
purchasecorresponde ac:purchasee aw:purchase.- Um nome com o prefixo, como
w:webinar.attended, corresponde só a ele. - Deixe vazio para iniciar com qualquer evento do workspace ou personalizado.
O campo sugere os eventos do workspace que você definiu e os eventos personalizados que o seu workspace enviou recentemente. Em Only when the properties match (optional), filtre pelas propriedades do evento, por exemplo properties.total Greater than 100. Para um evento do workspace, a lista de campos mostra as propriedades definidas dele.
O evento deve identificar um contato do workspace pelo ID ou pelo endereço de e-mail. Os eventos de visitantes anônimos, ou de endereços que não são contatos, não iniciam execuções. Na execução, {{payload.object.properties.total}} e similares contêm as propriedades.
Placed an order
Assim como o e-commerce, este gatilho está em alfa e aberto apenas à equipe do Emailit. As automações que já o usam continuam funcionando.
Dispara uma vez para cada novo pedido de um contato, vindo da API de pedidos ou do comando purchase do script de rastreamento. Os pedidos importados como histórico e os pedidos sem contato não o disparam, e as atualizações de um pedido não o disparam de novo. O filtro pode verificar Order total, Currency, Status, Source e Coupon codes do pedido, e os e-mails podem usar o pedido como {{payload.object.total}}, {{payload.object.external_id}} e assim por diante.
Abandoned a cart
Assim como o e-commerce, este gatilho está em alfa e aberto apenas à equipe do Emailit. As automações que já o usam continuam funcionando.
Dispara cada vez que um carrinho é abandonado: um carrinho de um contato conhecido que tem itens e não mudou durante o intervalo definido nas configurações de e-commerce (60 minutos por padrão). O filtro pode verificar Cart total, Currency e Source. Nos e-mails, {{cart}} mostra o carrinho; consulte Produtos, cupons e o carrinho.
As etapas Send email de uma execução iniciada por este gatilho são ignoradas quando esse carrinho vira um pedido, para que os compradores não recebam lembretes do que acabaram de comprar. Consulte a receita de carrinho abandonado.
A API também aceita contact.visits_url, mas nada o dispara ainda.
Viewed a product
Como o e-commerce, este gatilho está em alfa e aberto apenas à equipe do Emailit. As automações que já o usam continuam funcionando.
Dispara quando um contato vê um produto no seu site, pelo comando product do script de rastreamento ou pelo pixel do Emailit no Shopify. Qualquer pessoa com a sua chave de rastreamento pública pode enviar visualizações, então só disparam as visualizações de um contato que chegou por um dos seus e-mails (um link assinado) ou que se inscreveu em uma lista. O filtro pode verificar Product ID (shop), Product title e Price. Os e-mails podem usar {{payload.object.product.title}}, ou mostrar tudo o que o contato viu com {{products "recently_viewed"}}.
Uma visita costuma ter várias visualizações de produtos. Para o abandono de navegação, defina Wait between runs for the same contact (hours), espere antes do e-mail e saia com Placed an order, como faz o modelo Browse abandonment.
Product back in stock
Como o e-commerce, este gatilho está em alfa e aberto apenas à equipe do Emailit. As automações que já o usam continuam funcionando.
Dispara quando um produto que um contato pediu pelo formulário de volta ao estoque da sua loja Shopify volta a ficar disponível, uma vez por pedido. O filtro pode verificar Product ID (shop), Product title e Variant ID. Os e-mails podem usar {{payload.object.product.title}}, {{payload.object.product.url}}, {{payload.object.product.image_url}} e {{payload.object.variant.title}}. O modelo Back in stock envia o e-mail como transacional, porque o contato o pediu.
Gatilhos de e-mail
Os gatilhos de e-mail disparam para os e-mails do seu workspace: tudo o que você envia pela API ou por SMTP, os e-mails de campanhas e de automações e, para Email received, os e-mails recebidos. Cada execução se refere a um e-mail.
| Gatilho | Chave na API | Inicia uma execução quando | Campos do filtro |
|---|---|---|---|
| Email delivered | email.delivered |
O servidor do destinatário aceitou o e-mail. | From, To, Subject, Status |
| Email bounced | email.bounced |
O e-mail falhou de forma permanente. | From, To, Subject, Status |
| Email failed | email.failed |
O e-mail não pôde ser enviado por causa de um erro. | From, To, Subject, Status |
| Email suppressed | email.suppressed |
O e-mail não foi enviado porque o destinatário está suprimido. | From, To, Subject, Status |
| Email complained | email.complained |
O destinatário denunciou o e-mail como spam. | From, To, Subject, Status |
| Email received | email.received |
Chegou um e-mail. Consulte Recebimento de e-mails. | From, To, Subject |
| Email loaded | email.loaded |
O destinatário carregou um e-mail rastreado. | Recipient, Sender, Subject, IP address, User agent |
| Email clicked | email.clicked |
O destinatário clicou em um link rastreado. | Recipient, Sender, Subject, Link URL, IP address, User agent |
O editor também lista Email accepted, Email scheduled, Email attempted e Email rejected. As automações com esses gatilhos ainda não podem ser salvas, então escolha um dos gatilhos acima. Pela API, você também pode usar email.canceled, que dispara quando um e-mail agendado ou na fila é cancelado.
Gatilhos de evento
Por enquanto, as automações do contexto Event só podem ser criadas pela API.
| Gatilho | Chave na API | Inicia uma execução quando |
|---|---|---|
| Manual trigger | system.manual |
Você chama Disparar uma execução. |
| Schedule | system.schedule |
Reservado. Nada o dispara ainda, então chame o endpoint de disparo a partir do seu próprio agendador, como um cron job. |
Manual trigger
Chame o endpoint de disparo de uma automação em execução, com um objeto payload opcional:
curl https://api.emailit.com/v2/automations/aut_3Mv8Xq2nKp5Lt/trigger \
-X POST \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "payload": { "email": "ada@example.com", "plan": "pro" } }'O endpoint retorna { "message": "Automation trigger dispatched." }, ou 422 se a automação não estiver em execução. Ele inicia uma execução apenas dessa automação. As etapas podem ler o payload como {{payload.email}}, {{payload.plan}} e assim por diante. O Emailit adiciona automation_id ao payload.
system.manual também funciona como gatilho em automações dos contextos Contact e Email criadas pela API. Inclua contact_id (um ID con_) ou email_id no payload para executar a automação para esse contato ou e-mail.
Dados disponíveis para as etapas
As configurações das etapas, como o destinatário de Send email, os valores de Update contact fields ou o corpo de um Webhook, podem incluir variáveis que são preenchidas em cada execução:
| Variável | Contém |
|---|---|
{{contact.<field>}} |
O contato da execução, nas automações do contexto Contact, por exemplo {{contact.email}}, {{contact.score}} ou {{contact.custom_fields.plan}}. |
{{cf.<key>}} |
Um campo personalizado do contato, por exemplo {{cf.plan}}. |
{{tags}} |
As tags do contato, separadas por vírgulas. |
{{global.<key>}} |
Um valor global, por exemplo {{global.webinar_date}}. |
{{email.<field>}} |
O e-mail da execução, nas automações do contexto Email, por exemplo {{email.rcpt_to}} ou {{email.subject}}. |
{{payload.<path>}} |
O evento que iniciou a execução. Nos eventos no estilo de webhook, os dados do evento ficam em payload.object, por exemplo {{payload.object.to}}. Nos gatilhos manuais, é o seu payload. |
{{meta.<path>}} |
Dados extras que o Emailit armazena sobre a execução. |
{{run.id}} |
O ID da execução (aur_…). |
Os templates de e-mail enviados por Send email usam o Temple com os mesmos dados. Consulte Etapas.