# 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](/pt/docs/automations/#contexts), 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.
- **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.

### Filtros

Contact updated e todos os gatilhos de e-mail aceitam um filtro opcional, em **Filter events (optional)**. 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` ou `link.url`.

## 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. |
| **Contact updated** | `contact.updated` | Filtro opcional | O e-mail, os nomes, os campos personalizados ou o status de marketing de um contato mudam. |
| **Date anniversary** | `contact.date_anniversary` | **Date field** | Uma vez por ano, no mês e no dia armazenados em um campo personalizado de data. |

### 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](/pt/docs/api-reference/audiences/subscribers/add/), ou [Criar um contato](/pt/docs/api-reference/contacts/create/) com `audiences`) ou com a ação em massa **Add to audience**. 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](/pt/docs/contacts/import-export/), por uma inscrição pela [URL de inscrição](/pt/docs/audiences/subscribe-url/) ou pela etapa **Add to audience** ou **Create contact** de outra automação, e reativar **Subscribed** para um inscrito existente 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](/pt/docs/api-reference/audiences/subscribers/delete/) ou uma atualização de contato cuja lista `audiences` deixa a lista de fora. 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.

### Contact updated

Dispara sempre que um contato é atualizado no painel ou pela API, incluindo as ações em massa **Unsubscribe** e **Resubscribe**. 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`.

### Date anniversary

Escolha um **Date field**, um [campo personalizado](/pt/docs/contacts/custom-fields/) do tipo data, como um aniversário. Uma vez por dia, o Emailit inicia uma execução para cada contato cuja data tenha o mês e o dia de hoje, em UTC. O ano não importa, então um contato com `1990-04-12` recebe uma execução todo dia 12 de abril. Cada automação processa até 10.000 contatos por dia.

> **Defina o campo de data pela API:** No beta atual, a verificação diária lê a configuração `date_field` do gatilho, que o seletor **Date field** do painel ainda não define. Se a sua automação de aniversário não iniciar execuções, defina-a com [Atualizar uma automação](/pt/docs/api-reference/automations/update/): dê ao gatilho `"config": { "date_field": "birthday" }`, usando a chave do campo personalizado sem prefixo.

### Gatilhos de contato só pela API

| Chave na API | Inicia uma execução quando |
| --- | --- |
| `contact.loaded_email` | Um contato carrega um e-mail rastreado enviado para o endereço dele. |
| `contact.clicked_in_email` | Um contato clica em um link rastreado de um e-mail enviado para o endereço dele. |
| `contact.on_date` | O campo de data de um contato, definido em `config.date_field`, é igual à data de hoje em UTC. Dispara uma vez, e não todo ano. |

A API também aceita `contact.visits_url`, `contact.on_purchase` e `contact.on_event`, mas nada os dispara ainda.

## 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](/pt/docs/inbound/). | 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.

> **Evite loops:** Os e-mails enviados por automações também disparam gatilhos de e-mail. Uma automação que envia um e-mail sempre que um e-mail dá bounce também seria executada para a própria notificação, se ela desse bounce. Adicione um filtro, por exemplo **To** **Not equals** o seu endereço de alerta, para que uma automação não possa disparar a si mesma.

## 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](/pt/docs/api-reference/automations/trigger/). |
| 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:

```bash
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. As etapas podem ler o payload como `{{payload.email}}`, `{{payload.plan}}` e assim por diante. O Emailit adiciona `automation_id` ao payload.

> **Uma chamada alcança todas as automações manuais:** No beta atual, uma chamada ao endpoint de disparo inicia uma execução em todas as automações em execução do workspace cujo gatilho é **Manual trigger**, e não só na da URL. Se você tiver mais de uma, faça cada uma verificar antes o próprio ID com uma etapa **Condition** em `payload.automation_id`.

`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** ou os valores de **Edit contact**, 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}}` ou `{{contact.custom_fields.plan}}`. |
| `{{email.<field>}}` | O e-mail da execução, nas automações do contexto Email, por exemplo `{{email.rcpt_to}}` ou `{{email.subject}}`. |
| `{{payload.}}` | 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.}}` | Dados extras que o Emailit armazena sobre a execução. |

Os templates de e-mail enviados por **Send email** usam o [Temple](/pt/docs/templates/temple/) com os mesmos dados. Consulte [Etapas](/pt/docs/automations/steps/#send-email).

## Veja também

  - [Etapas](/pt/docs/automations/steps/): O que uma execução pode fazer depois de começar.
  - [Tipos de eventos de webhook](/pt/docs/webhooks/event-types/): Os eventos por trás dos gatilhos de contato e de e-mail.

---
Fonte: https://emailit.com/pt/docs/automations/triggers/