# Automações API > Monte fluxos com gatilhos e etapas, execute-os e inspecione as execuções. URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer `. ## Criar uma automação — POST /automations > Crie uma automação em rascunho a partir de um grafo de etapas de gatilho e de ação, como um e-mail de boas-vindas enviado quando um contato entra em uma lista de contatos. # Criar uma automação Cria uma automação com status `draft` a partir de um grafo de etapas e conexões. Requer uma chave de API com escopo `full`. As automações estão em beta. A automação não faz nada até você [iniciá-la](/pt/docs/api-reference/automations/start/). Cada execução custa 3 créditos ao começar, e cada e-mail enviado por `send_email` ou `forward_email` custa mais 1 crédito. Em um workspace não verificado, essas ações só podem enviar para os e-mails das contas dos membros do workspace. `POST /automations` ## Parâmetros do corpo - `context` (string, obrigatório): A que cada execução se refere: `contact`, `email` ou `event`. O contexto define quais gatilhos e ações você pode usar e não pode ser alterado depois. Consulte [Contextos](#contexts). - `name` (string, obrigatório): Nome da automação, com até 191 caracteres. - `description` (string | null): Descrição opcional. - `settings` (object): Regras de execução. Consulte [Configurações](#settings). - `steps` (object[], obrigatório): As etapas de gatilho e de ação, com pelo menos um gatilho. Consulte [Etapas](#steps). - `connections` (object[], obrigatório): As arestas entre as etapas. Passe `[]` para um grafo que só tem um gatilho. Consulte [Conexões](#connections). ### Configurações - `on_step_failure` (string): `stop` marca a execução como `failed` quando uma etapa falha. `skip` registra a etapa com falha e deixa o restante da execução terminar. - `allow_reentry` (boolean): `false` ignora um gatilho quando o mesmo contato (ou e-mail) já tem uma execução em andamento nesta automação. - `max_concurrent_runs` (integer): Número máximo de execuções com status `running` ao mesmo tempo. `0` significa sem limite. - `cooldown_seconds` (integer): Ignora um gatilho quando o mesmo contato (ou e-mail) iniciou uma execução nesta automação dentro desse número de segundos. ### Etapas - `key` (string, obrigatório): O seu identificador da etapa, único dentro da automação, por exemplo `welcome_email`. As conexões, as [estatísticas das etapas](/pt/docs/api-reference/automations/step-stats/) e as atualizações se referem às etapas pela chave. - `type` (string, obrigatório): `trigger` ou `action`. - `trigger` (string): Nome do gatilho, obrigatório quando `type` é `trigger`. Consulte [Gatilhos](#triggers). - `action` (string): Nome da ação, obrigatório quando `type` é `action`. Consulte [Ações](#actions). - `config` (object): Configurações do gatilho ou da ação. ### Conexões - `from` (string, obrigatório): Chave da etapa em que a aresta começa. - `to` (string, obrigatório): Chave da próxima etapa. - `branch` (string): Qual resultado da etapa `from` segue esta aresta. Etapas `condition` usam `yes` e `no`; etapas `experiment` usam as chaves das variantes. Todas as outras etapas usam `default`. ## Contextos | Contexto | Uma execução se refere a | Gatilhos | Regras | | --- | --- | --- | --- | | `contact` | Um contato. `send_email` envia para esse contato. | `contact.*`, `system.*` | Um ou mais gatilhos. Todos devem se conectar à mesma primeira ação. | | `email` | Um e-mail (enviado ou recebido). | `email.*`, `system.*` | Um ou mais gatilhos. Todos devem se conectar à mesma primeira ação. | | `event` | Apenas o payload do gatilho. | `event.*`, `system.*` | Exatamente um gatilho. | Toda ação deve ser alcançável a partir de um gatilho. Uma execução começa na ação conectada ao gatilho que disparou e segue as conexões: - `condition` segue apenas a aresta cujo `branch` é `yes` ou `no`, conforme o resultado. - `experiment` segue as arestas da variante escolhida. Quando esse caminho termina, a execução continua pelas arestas `default` da etapa de experimento. - `wait` adia a próxima etapa. - Todas as outras ações seguem as arestas `default` delas. Uma etapa com várias arestas de saída executa todas elas. Uma execução fica `completed` quando não restam etapas, `failed` quando uma etapa falha (com `on_step_failure: "stop"`) e `canceled` quando você [interrompe a automação](/pt/docs/api-reference/automations/stop/). ## Gatilhos | Gatilho | Contexto | Dispara quando | | --- | --- | --- | | `contact.added_to_audience` | contact | Um contato se inscreve em uma lista de contatos, incluindo reinscrições. | | `contact.removed_from_audience` | contact | Um inscrito é excluído de uma lista de contatos. | | `contact.updated` | contact | Um contato é atualizado. | | `contact.loaded_email` | contact | Um destinatário que é contato no workspace abre um e-mail. | | `contact.clicked_in_email` | contact | Um destinatário que é contato no workspace clica em um link rastreado. | | `contact.date_anniversary` | contact | Diariamente às 00:00 UTC, para os contatos cujo campo personalizado de data (`YYYY-MM-DD`) tem o mês e o dia de hoje. | | `contact.on_date` | contact | Diariamente às 00:00 UTC, para os contatos cujo campo personalizado de data é igual à data de hoje. | | `contact.visits_url`, `contact.on_purchase`, `contact.on_event` | contact | Aceitos, mas o Emailit ainda não os dispara. | | `email.received` | email | Chega um e-mail recebido. | | `email.delivered`, `email.bounced`, `email.complained`, `email.loaded`, `email.clicked`, `email.failed`, `email.suppressed`, `email.canceled` | email | Ocorre o evento de e-mail de mesmo nome. | | `event.` | event | Qualquer nome que comece com `event.`. O Emailit ainda não emite eventos `event.*`; inicie as automações de evento com `system.manual`. | | `system.manual` | todos | Você chama [Disparar uma execução](/pt/docs/api-reference/automations/trigger/). | | `system.schedule` | todos | Aceito, mas o Emailit ainda não dispara gatilhos agendados. | Campos de `config` dos gatilhos: - `audience_id` (string): Para `contact.added_to_audience` e `contact.removed_from_audience`: dispara apenas para esta lista de contatos (`aud_…`). - `date_field` (string): Para `contact.date_anniversary` e `contact.on_date`: a chave do [campo personalizado](/pt/docs/contacts/custom-fields/) que guarda a data, por exemplo `birthday`. - `filter` (object): Dispara apenas quando o evento corresponde: `{ "match": "all", "rules": [{ "field": "subject", "operator": "contains", "value": "Invoice" }] }`. `match` é `all` (padrão) ou `any`. `field` é um caminho com pontos dentro do `object` do evento, por exemplo `to` ou `email.subject`; um `payload.` inicial é ignorado. Operadores: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `in`, `not_in`, `is_set`, `is_not_set`. Todos os operadores, exceto `is_set` e `is_not_set`, precisam de um `value`; `in` e `not_in` recebem um array. ## Ações | Ação | Contexto | Configuração | | --- | --- | --- | | `send_email` | todos | `type` (obrigatório, `template`), `template_id` (obrigatório: um ID `tem_` ou o alias de um template publicado), `from`, `subject`, `reply_to`, `to` | | `forward_email` | email, event | `to` (obrigatório), `from`, `subject`, `email_id` | | `wait` | todos | `seconds` (obrigatório, de 0 a 2.592.000, ou seja, 30 dias) | | `condition` | todos | `filter` (obrigatório, veja abaixo) | | `experiment` | todos | `variants` (obrigatório), `control` | | `call_webhook` | todos | `url` (obrigatório), `method`, `headers`, `body` | | `run_automation` | todos | `automation_id` (obrigatório) | | `end` | todos | Nenhuma | | `add_to_audience` | contact | `audience_id` (obrigatório) | | `remove_from_audience` | contact | `audience_id` (obrigatório) | | `edit_contact` | contact | `fields` (obrigatório) | | `add_to_suppressions` | email, event | `type`, `reason`, `email` | | `remove_from_suppressions` | email, event | `email` | | `create_contact` | email, event | `email`, `first_name`, `audience_id` | - **`send_email`** envia o template. Por padrão, `from` é o remetente do template e deve estar em um domínio de envio verificado. `subject` substitui o assunto do template. `reply_to` é um endereço ou um array de endereços. No contexto `contact`, o e-mail vai para o contato da execução; nos contextos `email` e `event`, defina `to`. - **`forward_email`** encaminha o e-mail da execução (ou o e-mail em `email_id`) para `to`. Por padrão, `from` é o remetente original e `subject` é `Fwd: `. - **`condition`** recebe `{ "match": "all" | "any", "rules": [...] }` com os mesmos operadores dos filtros de gatilho. Campos sem prefixo são resolvidos no contato (`first_name`, `custom_fields.plan`) ou no e-mail (`rcpt_to`, `subject`) da execução; prefixe um campo com `contact.`, `email.`, `payload.` ou `meta.` para ser explícito. A etapa continua em `yes` ou `no`. - **`experiment`** escolhe aleatoriamente, de acordo com o peso, uma das `variants` (ou `control`), cada uma no formato `{ "key": "a", "weight": 50 }`, e continua na ramificação com o nome da chave escolhida. - **`call_webhook`** envia uma requisição HTTP (método padrão `POST`, `Content-Type` JSON) e registra a classe do status (`2xx`, `4xx`, `5xx`), `timeout` ou `network_error`. Uma resposta diferente de 2xx não faz a etapa falhar. - **`run_automation`** inicia uma execução de outra automação em andamento com o payload desta execução. A execução atual continua. - **`edit_contact`** recebe `fields: [{ "key": "first_name", "value": "Ada" }]`. As chaves `email`, `first_name`, `last_name` e `unsubscribed` atualizam o contato; qualquer outra chave define um campo personalizado. - **`add_to_suppressions`** suprime o endereço da execução (`type` padrão `recipient`, `reason` padrão `automation`). **`remove_from_suppressions`** remove a supressão. No contexto `event`, passe `email`. - **`create_contact`** cria o contato (ou encontra o existente) e, opcionalmente, o inscreve em `audience_id`. No contexto `email`, o padrão de `email` é o destinatário do e-mail. Os valores de string em qualquer configuração de ação podem usar placeholders que o Emailit preenche quando a etapa é executada: `{{contact.email}}`, `{{email.mail_from}}`, `{{payload.object.subject}}` ou `{{meta.source_event_id}}`, por exemplo `"to": "{{email.mail_from}}"`. Os templates enviados por `send_email` também renderizam diretamente os campos do contato, como `{{ first_name }}`. ## Retorno Retorna `201 Created` com a automação em `data`, incluindo o ID de cada etapa (`aus_…`) e as conexões. `status` é `draft`. A criação verifica a estrutura do grafo: nomes de gatilhos e ações válidos para o contexto, chaves únicas, conexões válidas, alcançabilidade e se todo endereço `from` de `send_email` usa um domínio de envio verificado. Ela não verifica se a configuração de cada ação está completa; [Atualizar uma automação](/pt/docs/api-reference/automations/update/) verifica. Os erros retornam `400` com `errors` organizados pelo caminho do campo. **Requisição** `POST /automations` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Welcome series", "context": "contact", "description": "Welcome new subscribers, then nudge free users a day later.", "settings": { "allow_reentry": false }, "steps": [ { "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "key": "welcome_email", "type": "action", "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } }, { "key": "wait_1_day", "type": "action", "action": "wait", "config": { "seconds": 86400 } }, { "key": "is_free_user", "type": "action", "action": "condition", "config": { "filter": { "match": "all", "rules": [{ "field": "custom_fields.plan", "operator": "is_not_set" }] } } }, { "key": "upgrade_tips", "type": "action", "action": "send_email", "config": { "type": "template", "template_id": "getting-started-tips" } }, { "key": "done", "type": "action", "action": "end" } ], "connections": [ { "from": "joined", "to": "welcome_email" }, { "from": "welcome_email", "to": "wait_1_day" }, { "from": "wait_1_day", "to": "is_free_user" }, { "from": "is_free_user", "to": "upgrade_tips", "branch": "yes" }, { "from": "is_free_user", "to": "done", "branch": "no" } ] }' ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Welcome series', context: 'contact', description: 'Welcome new subscribers, then nudge free users a day later.', settings: { allow_reentry: false }, steps: [ { key: 'joined', type: 'trigger', trigger: 'contact.added_to_audience', config: { audience_id: 'aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV' }, }, { key: 'welcome_email', type: 'action', action: 'send_email', config: { type: 'template', template_id: 'welcome', from: 'Acme ' }, }, { key: 'wait_1_day', type: 'action', action: 'wait', config: { seconds: 86400 } }, { key: 'is_free_user', type: 'action', action: 'condition', config: { filter: { match: 'all', rules: [{ field: 'custom_fields.plan', operator: 'is_not_set' }] }, }, }, { key: 'upgrade_tips', type: 'action', action: 'send_email', config: { type: 'template', template_id: 'getting-started-tips' }, }, { key: 'done', type: 'action', action: 'end' }, ], connections: [ { from: 'joined', to: 'welcome_email' }, { from: 'welcome_email', to: 'wait_1_day' }, { from: 'wait_1_day', to: 'is_free_user' }, { from: 'is_free_user', to: 'upgrade_tips', branch: 'yes' }, { from: 'is_free_user', to: 'done', branch: 'no' }, ], }), }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, json={ "name": "Welcome series", "context": "contact", "description": "Welcome new subscribers, then nudge free users a day later.", "settings": {"allow_reentry": False}, "steps": [ { "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "config": {"audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV"}, }, { "key": "welcome_email", "type": "action", "action": "send_email", "config": {"type": "template", "template_id": "welcome", "from": "Acme "}, }, {"key": "wait_1_day", "type": "action", "action": "wait", "config": {"seconds": 86400}}, { "key": "is_free_user", "type": "action", "action": "condition", "config": { "filter": { "match": "all", "rules": [{"field": "custom_fields.plan", "operator": "is_not_set"}], } }, }, { "key": "upgrade_tips", "type": "action", "action": "send_email", "config": {"type": "template", "template_id": "getting-started-tips"}, }, {"key": "done", "type": "action", "action": "end"}, ], "connections": [ {"from": "joined", "to": "welcome_email"}, {"from": "welcome_email", "to": "wait_1_day"}, {"from": "wait_1_day", "to": "is_free_user"}, {"from": "is_free_user", "to": "upgrade_tips", "branch": "yes"}, {"from": "is_free_user", "to": "done", "branch": "no"}, ], }, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'json' => [ 'name' => 'Welcome series', 'context' => 'contact', 'description' => 'Welcome new subscribers, then nudge free users a day later.', 'settings' => ['allow_reentry' => false], 'steps' => [ [ 'key' => 'joined', 'type' => 'trigger', 'trigger' => 'contact.added_to_audience', 'config' => ['audience_id' => 'aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV'], ], [ 'key' => 'welcome_email', 'type' => 'action', 'action' => 'send_email', 'config' => ['type' => 'template', 'template_id' => 'welcome', 'from' => 'Acme '], ], ['key' => 'wait_1_day', 'type' => 'action', 'action' => 'wait', 'config' => ['seconds' => 86400]], [ 'key' => 'is_free_user', 'type' => 'action', 'action' => 'condition', 'config' => [ 'filter' => [ 'match' => 'all', 'rules' => [['field' => 'custom_fields.plan', 'operator' => 'is_not_set']], ], ], ], [ 'key' => 'upgrade_tips', 'type' => 'action', 'action' => 'send_email', 'config' => ['type' => 'template', 'template_id' => 'getting-started-tips'], ], ['key' => 'done', 'type' => 'action', 'action' => 'end'], ], 'connections' => [ ['from' => 'joined', 'to' => 'welcome_email'], ['from' => 'welcome_email', 'to' => 'wait_1_day'], ['from' => 'wait_1_day', 'to' => 'is_free_user'], ['from' => 'is_free_user', 'to' => 'upgrade_tips', 'branch' => 'yes'], ['from' => 'is_free_user', 'to' => 'done', 'branch' => 'no'], ], ], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **201** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "draft", "settings": { "allow_reentry": false }, "last_triggered_at": null, "published_at": null, "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-01T09:41:05.318274+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } }, { "id": "aus_3vM0ORwEXCQcyS7rylfQBQEXjVk", "key": "wait_1_day", "type": "action", "trigger": null, "action": "wait", "config": { "seconds": 86400 } }, { "id": "aus_3HOgOzxaXBgVRpLFtpvJNo4vd5c", "key": "is_free_user", "type": "action", "trigger": null, "action": "condition", "config": { "filter": { "match": "all", "rules": [{ "field": "custom_fields.plan", "operator": "is_not_set" }] } } }, { "id": "aus_3gCI5SWMPFVhOSawR6nz8sF55wp", "key": "upgrade_tips", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "getting-started-tips" } }, { "id": "aus_3Pq7Wd2LxN8cVt5RmK0sHy4BfJe", "key": "done", "type": "action", "trigger": null, "action": "end", "config": {} } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" }, { "from": "welcome_email", "to": "wait_1_day", "branch": "default" }, { "from": "wait_1_day", "to": "is_free_user", "branch": "default" }, { "from": "is_free_user", "to": "upgrade_tips", "branch": "yes" }, { "from": "is_free_user", "to": "done", "branch": "no" } ] }, "message": "Automation was successfully created.", "notify": true } ``` **400** ```json { "message": "Validation failed.", "errors": { "steps.1.action": ["Action \"forward_email\" is not allowed for context \"contact\"."], "steps": ["Action step \"upgrade_tips\" is not reachable from any trigger."] } } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/create/ ## Obter uma automação — GET /automations/{id} > Obtenha uma automação com o status, as configurações, as etapas de gatilho e de ação e as conexões entre elas. # Obter uma automação Obtém uma automação com o grafo completo. Requer uma chave de API com escopo `full`. `GET /automations/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Retorno Retorna a automação em `data`. - `id` (string): ID da automação, com o prefixo `aut_`. - `context` (string): `contact`, `email` ou `event`. - `name` (string): Nome da automação. - `description` (string | null): Descrição opcional. - `status` (string): `draft`, `running`, `paused`, `stopped` ou `archived`. - `settings` (object): Regras de execução: `on_step_failure`, `allow_reentry`, `max_concurrent_runs`, `cooldown_seconds`. Vazio quando você não definiu nenhuma. - `last_triggered_at` (string | null): Quando a automação iniciou uma execução pela última vez. - `published_at` (string | null): Quando a automação foi iniciada pela primeira vez. - `steps` (object[]): O `id` (`aus_…`), a `key`, o `type`, o `trigger`, a `action` e a `config` de cada etapa. Os detalhes de uma execução se referem às etapas pelo `id`; as estatísticas, pela `key`. - `connections` (object[]): As chaves das etapas `from` e `to` de cada aresta e o `branch` dela. Consulte [Criar uma automação](/pt/docs/api-reference/automations/create/) para saber o significado de cada gatilho, ação e configuração. Retorna `404` se a automação não existir ou tiver sido excluída. **Requisição** `GET /automations/{id}` **cURL** ```bash curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "running", "settings": { "allow_reentry": false }, "last_triggered_at": "2026-10-03T14:12:40.551870+00:00", "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-03T14:12:40.551870+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } }, { "id": "aus_3vM0ORwEXCQcyS7rylfQBQEXjVk", "key": "wait_1_day", "type": "action", "trigger": null, "action": "wait", "config": { "seconds": 86400 } } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" }, { "from": "welcome_email", "to": "wait_1_day", "branch": "default" } ] } } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/get/ ## Atualizar uma automação — POST /automations/{id} > Renomeie uma automação, altere as configurações dela ou substitua o grafo de etapas e conexões, com validação completa. # Atualizar uma automação Atualiza o nome, a descrição, as configurações ou o grafo de uma automação. Requer uma chave de API com escopo `full`. O contexto não pode ser alterado. Para alterar o grafo, envie `steps` e `connections` juntos; eles substituem o grafo atual. As etapas cuja `key` já existe mantêm o ID e o histórico de execuções, as etapas que você deixar de fora são excluídas e as novas chaves são adicionadas. Ao contrário da criação, a atualização também valida a configuração de cada ação (por exemplo, `send_email` precisa de `type` e `template_id`, e `wait` precisa de `seconds`). [Pause a automação](/pt/docs/api-reference/automations/pause/) antes de alterar o grafo de uma automação em andamento e depois [inicie-a](/pt/docs/api-reference/automations/start/) de novo para que os novos gatilhos entrem em vigor. `POST /automations/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Parâmetros do corpo - `name` (string): Nome, com até 191 caracteres. - `description` (string): Descrição. - `settings` (object): Substitui todas as configurações: `on_step_failure`, `allow_reentry`, `max_concurrent_runs`, `cooldown_seconds`. Consulte [Configurações](/pt/docs/api-reference/automations/create/#settings). - `steps` (object[]): A lista completa de etapas. Obrigatório quando você envia `connections`. Consulte [Etapas](/pt/docs/api-reference/automations/create/#steps). - `connections` (object[]): A lista completa de conexões. Obrigatório quando você envia `steps`. Consulte [Conexões](/pt/docs/api-reference/automations/create/#connections). ## Retorno Retorna a automação atualizada em `data`, com `message` e `notify`. Retorna `400` com `errors` organizados pelo caminho do campo quando a validação falha, e `404` se a automação não existir. **Requisição** `POST /automations/{id}` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Welcome series (v2)", "settings": { "allow_reentry": false, "on_step_failure": "skip" } }' ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Welcome series (v2)', settings: { allow_reentry: false, on_step_failure: 'skip' }, }), }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, json={ "name": "Welcome series (v2)", "settings": {"allow_reentry": False, "on_step_failure": "skip"}, }, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'json' => [ 'name' => 'Welcome series (v2)', 'settings' => ['allow_reentry' => false, 'on_step_failure' => 'skip'], ], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series (v2)", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "paused", "settings": { "allow_reentry": false, "on_step_failure": "skip" }, "last_triggered_at": "2026-10-03T14:12:40.551870+00:00", "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-04T08:15:22.730115+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" } ] }, "message": "Automation was successfully updated.", "notify": true } ``` **400** ```json { "message": "Validation failed.", "errors": { "steps.2.config.seconds": ["Wait seconds cannot exceed 2592000 (30 days)."], "steps.1.config.template_id": ["Template ID is required when type is \"template\"."] } } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/update/ ## Listar automações — GET /automations > Liste as automações de um workspace com paginação por page e per_page, filtradas por contexto, status ou nome. # Listar automações Retorna as automações do workspace, das mais recentes para as mais antigas, sem as etapas e as conexões. Requer uma chave de API com escopo `full`. Automações excluídas não são listadas. `GET /automations` ## Parâmetros de consulta - `page` (integer): Número da página, a partir de 1. - `per_page` (integer): Automações por página, de 1 a 100. - `filter[context]` (string): Apenas automações com este contexto: `contact`, `email` ou `event`. - `filter[status]` (string): Apenas automações com este status: `draft`, `running`, `paused`, `stopped` ou `archived`. - `filter[name]` (string): Busca sem diferenciar maiúsculas de minúsculas em parte do nome. - `sort` (string): Campo de ordenação: `name`, `created_at`, `updated_at` ou `last_triggered_at`. - `order` (string): Direção da ordenação: `asc` ou `desc`. Você também pode usar os filtros genéricos `key.condition=value` em `name`, `status`, `context` e `created_at`, com `match`. Consulte [Filtragem](/pt/docs/api-reference/filtering/). ## Retorno - `data` (object[]): As automações desta página: `id`, `context`, `name`, `description`, `status`, `settings`, `last_triggered_at`, `published_at`, `created_at`, `updated_at`. Nesta listagem, `settings` é sempre um objeto vazio; [obtenha a automação](/pt/docs/api-reference/automations/get/) para lê-lo. - `total_records` (integer): Número de automações que correspondem. - `per_page` (integer): Tamanho de página usado. - `current_page` (integer): O número desta página. - `total_pages` (integer): Número de páginas. **Requisição** `GET /automations` **cURL** ```bash curl -G https://api.emailit.com/v2/automations \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ --data-urlencode "filter[status]=running" \ -d sort=last_triggered_at \ -d per_page=50 ``` **Node.js** ```javascript const params = new URLSearchParams({ 'filter[status]': 'running', sort: 'last_triggered_at', per_page: '50' }); const res = await fetch(`https://api.emailit.com/v2/automations?${params}`, { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const { data, total_pages } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, params={"filter[status]": "running", "sort": "last_triggered_at", "per_page": 50}, ) automations = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'query' => ['filter[status]' => 'running', 'sort' => 'last_triggered_at', 'per_page' => 50], ]); $automations = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": [ { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "running", "settings": {}, "last_triggered_at": "2026-10-03T14:12:40.551870+00:00", "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-03T14:12:40.551870+00:00" } ], "total_records": 1, "per_page": 50, "current_page": 1, "total_pages": 1 } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/list/ ## Excluir uma automação — DELETE /automations/{id} > Exclua uma automação para que ela pare de reagir aos gatilhos. Interrompa-a antes se também quiser cancelar as execuções em andamento. # Excluir uma automação Exclui uma automação. Ela desaparece das listagens e para de reagir aos gatilhos. Requer uma chave de API com escopo `full`. As execuções que já estão em andamento não são canceladas. Para cancelá-las, [interrompa a automação](/pt/docs/api-reference/automations/stop/) antes de excluí-la. `DELETE /automations/{id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Retorno Retorna uma `message` confirmando a exclusão. Retorna `404` se a automação não existir ou já tiver sido excluída. **Requisição** `DELETE /automations/{id}` **cURL** ```bash curl -X DELETE https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const result = await res.json(); ``` **Python** ```python import os, requests r = requests.delete( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) result = r.json() ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->delete('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $result = json_decode($response->getBody(), true); ``` **200** ```json { "message": "Automation was deleted successfully.", "notify": true } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/delete/ ## Iniciar uma automação — POST /automations/{id}/start > Coloque uma automação em execução para que os gatilhos dela iniciem novas execuções. Funciona com automações em rascunho, pausadas e interrompidas. # Iniciar uma automação Define o status da automação como `running`. A partir desse momento, os gatilhos correspondentes iniciam execuções; os eventos que aconteceram antes de você iniciá-la, não. Requer uma chave de API com escopo `full`. Você pode iniciar uma automação `draft`, `paused` ou `stopped`. O primeiro início define `published_at`. Iniciar não valida o grafo de novo. Se você montou a automação com [Criar uma automação](/pt/docs/api-reference/automations/create/), que verifica apenas a estrutura, confira se a configuração de cada ação está completa, ou envie o grafo uma vez por [Atualizar uma automação](/pt/docs/api-reference/automations/update/), que o valida por completo. Uma etapa com configuração incompleta falha quando uma execução chega a ela. `POST /automations/{id}/start` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Retorno Retorna a automação em `data` com `status` definido como `running`. Retorna `404` se a automação não existir. **Requisição** `POST /automations/{id}/start` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/start \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/start', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/start", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/start', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "running", "settings": { "allow_reentry": false }, "last_triggered_at": null, "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-01T10:00:02.204118+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" } ] }, "message": "Automation was successfully started.", "notify": true } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/start/ ## Pausar uma automação — POST /automations/{id}/pause > Pause uma automação para que os gatilhos dela parem de iniciar novas execuções, enquanto as execuções já em andamento continuam até o fim. # Pausar uma automação Define o status da automação como `paused`. Os gatilhos dela param de iniciar novas execuções, mas as execuções já em andamento continuam, incluindo as que estão aguardando em uma etapa `wait`. Requer uma chave de API com escopo `full`. Para também cancelar as execuções em andamento, [interrompa a automação](/pt/docs/api-reference/automations/stop/) em vez de pausá-la. [Inicie-a](/pt/docs/api-reference/automations/start/) de novo para retomar os disparos. `POST /automations/{id}/pause` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Retorno Retorna a automação em `data` com `status` definido como `paused`. Retorna `404` se a automação não existir. **Requisição** `POST /automations/{id}/pause` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/pause \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/pause', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/pause", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/pause', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "paused", "settings": { "allow_reentry": false }, "last_triggered_at": "2026-10-03T14:12:40.551870+00:00", "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-04T08:10:51.004732+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" } ] }, "message": "Automation was successfully paused.", "notify": true } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/pause/ ## Interromper uma automação — POST /automations/{id}/stop > Interrompa uma automação e cancele todas as execuções em andamento dela. Disponível apenas pela API, não no painel. # Interromper uma automação Define o status da automação como `stopped` e cancela todas as execuções que ainda estão `running`; essas execuções recebem o status `canceled`, e as etapas restantes delas não são executadas. Requer uma chave de API com escopo `full`. A interrupção está disponível apenas pela API. Para manter as execuções em andamento, [pause a automação](/pt/docs/api-reference/automations/pause/) em vez de interrompê-la. Você pode [iniciar](/pt/docs/api-reference/automations/start/) de novo uma automação interrompida; as novas execuções começam do zero. `POST /automations/{id}/stop` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Retorno Retorna a automação em `data` com `status` definido como `stopped`. Retorna `404` se a automação não existir. **Requisição** `POST /automations/{id}/stop` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stop \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stop', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` }, }); const { data: automation } = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stop", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) automation = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stop', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $automation = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "context": "contact", "name": "Welcome series", "description": "Welcome new subscribers, then nudge free users a day later.", "status": "stopped", "settings": { "allow_reentry": false }, "last_triggered_at": "2026-10-03T14:12:40.551870+00:00", "published_at": "2026-10-01T10:00:02.204118+00:00", "created_at": "2026-10-01T09:41:05.318274+00:00", "updated_at": "2026-10-05T16:45:09.882301+00:00", "steps": [ { "id": "aus_3ZqpuxjmL1szZ8og6uGL1mT6QEJ", "key": "joined", "type": "trigger", "trigger": "contact.added_to_audience", "action": null, "config": { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" } }, { "id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "key": "welcome_email", "type": "action", "trigger": null, "action": "send_email", "config": { "type": "template", "template_id": "welcome", "from": "Acme " } } ], "connections": [ { "from": "joined", "to": "welcome_email", "branch": "default" } ] }, "message": "Automation was successfully stopped.", "notify": true } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/stop/ ## Disparar uma execução — POST /automations/{id}/trigger > Dispare o gatilho system.manual de uma automação em andamento com o seu próprio payload para iniciar uma execução a partir do seu código. # Disparar uma execução Dispara o gatilho `system.manual` com um payload escolhido por você. A automação precisa estar `running` e ter uma etapa de gatilho `system.manual`; caso contrário, nenhuma execução é iniciada. Requer uma chave de API com escopo `full`. Os gatilhos manuais estão disponíveis apenas pela API. A execução começa de forma assíncrona e custa 3 créditos, como qualquer outra execução. Encontre-a com [Listar execuções](/pt/docs/api-reference/automations/runs/). > **Todos os gatilhos manuais do workspace disparam:** No momento, o Emailit entrega o gatilho manual a todas as automações em andamento no workspace que têm uma etapa de gatilho `system.manual`, e não apenas à automação do caminho. Para limitar uma automação às próprias chamadas, adicione um filtro à etapa de gatilho dela: `{ "match": "all", "rules": [{ "field": "automation_id", "operator": "equals", "value": "aut_…" }] }`. `POST /automations/{id}/trigger` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Parâmetros do corpo - `payload` (object): Os dados da execução. O Emailit adiciona `automation_id` e guarda o resultado como o `payload` da execução. As etapas podem lê-lo com placeholders como `{{payload.order_id}}` e condições como `payload.plan`. A que a execução se refere depende do contexto da automação: - `contact`: passe `contact_id` (`con_…`). As ações de contato e `send_email` usam esse contato. - `email`: passe `email_id` (`em_…`). As ações de e-mail usam esse e-mail. - `event`: quaisquer dados. Defina `to` ou `email` nas configurações das ações, por exemplo `"to": "{{payload.customer_email}}"`. ## Retorno Retorna `200` com uma `message` assim que o gatilho é colocado na fila. Retorna `422` se a automação não estiver `running` e `404` se ela não existir. **Requisição** `POST /automations/{id}/trigger` **cURL** ```bash curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/trigger \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "payload": { "contact_id": "con_3munwNLaXKUARc6ff9wPtxKVq4A", "plan": "pro", "order_id": "ord_1042" } }' ``` **Node.js** ```javascript const res = await fetch('https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/trigger', { method: 'POST', headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ payload: { contact_id: 'con_3munwNLaXKUARc6ff9wPtxKVq4A', plan: 'pro', order_id: 'ord_1042' }, }), }); const result = await res.json(); ``` **Python** ```python import os, requests r = requests.post( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/trigger", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, json={"payload": {"contact_id": "con_3munwNLaXKUARc6ff9wPtxKVq4A", "plan": "pro", "order_id": "ord_1042"}}, ) result = r.json() ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->post('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/trigger', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'json' => [ 'payload' => ['contact_id' => 'con_3munwNLaXKUARc6ff9wPtxKVq4A', 'plan' => 'pro', 'order_id' => 'ord_1042'], ], ]); $result = json_decode($response->getBody(), true); ``` **200** ```json { "message": "Automation trigger dispatched." } ``` **422** ```json { "message": "Automation must be running to trigger." } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/trigger/ ## Listar execuções — GET /automations/{id}/runs > Liste as execuções de uma automação, das mais recentes para as mais antigas, com o evento que as disparou, o payload, o status e os horários de cada uma. # Listar execuções Retorna as execuções de uma automação, das mais recentes para as mais antigas. Cada execução é uma passagem pelo grafo, iniciada por um gatilho. Requer uma chave de API com escopo `full`. `GET /automations/{id}/runs` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Parâmetros de consulta - `page` (integer): Número da página, a partir de 1. - `per_page` (integer): Execuções por página, de 1 a 100. - `filter[status]` (string): Apenas execuções com este status: `running`, `completed`, `failed` ou `canceled`. Você também pode filtrar com `key.condition=value` em `status`, `event` e `created_at` (por exemplo `created_at.after=2026-10-01`) e ordenar com `order` e `direction` pelas mesmas chaves. Consulte [Filtragem](/pt/docs/api-reference/filtering/). ## Retorno - `data` (object[]): As execuções desta página. Veja os campos abaixo. - `total_records, per_page, current_page, total_pages` (integer): Detalhes da paginação. Cada execução tem: - `id` (string): ID da execução, com o prefixo `aur_`. - `automation_id` (string): A automação (`aut_…`). - `contact_id` (string | null): O contato da execução (`con_…`) no contexto `contact`. - `email_id` (string | null): O e-mail da execução (`em_…`) no contexto `email`. - `event_id` (string | null): ID do evento de origem, quando o payload do gatilho tiver um. - `event` (string): O gatilho que iniciou a execução, por exemplo `contact.added_to_audience` ou `system.manual`. - `payload` (object): Sempre um objeto vazio nesta listagem. [Obtenha a execução](/pt/docs/api-reference/automations/run/) para ler o payload do gatilho. - `meta` (object): Sempre um objeto vazio nesta listagem. Obtenha a execução para ler os metadados dela, como `failure_reason`. - `status` (string): `running`, `completed`, `failed` ou `canceled` (a automação foi interrompida). - `started_at, completed_at, created_at, updated_at` (string | null): Timestamps em UTC. **Requisição** `GET /automations/{id}/runs` **cURL** ```bash curl -G https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ --data-urlencode "filter[status]=failed" ``` **Node.js** ```javascript const params = new URLSearchParams({ 'filter[status]': 'failed' }); const res = await fetch( `https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs?${params}`, { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } }, ); const { data: runs } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, params={"filter[status]": "failed"}, ) runs = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'query' => ['filter[status]' => 'failed'], ]); $runs = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": [ { "id": "aur_3q6GdFk2eRSG093grI0v9e6REu8", "automation_id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "contact_id": "con_3munwNLaXKUARc6ff9wPtxKVq4A", "email_id": null, "event_id": null, "event": "contact.added_to_audience", "payload": {}, "meta": {}, "status": "failed", "started_at": "2026-10-03T14:12:40.551870+00:00", "completed_at": "2026-10-03T14:12:41.093355+00:00", "created_at": "2026-10-03T14:12:40.551870+00:00", "updated_at": "2026-10-03T14:12:41.093355+00:00" } ], "total_records": 1, "per_page": 25, "current_page": 1, "total_pages": 1 } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/runs/ ## Obter uma execução — GET /automations/{id}/runs/{run_id} > Obtenha uma execução de automação com o payload do gatilho, os metadados e o status e o resultado de cada etapa executada. # Obter uma execução Obtém uma execução de uma automação, incluindo as etapas que ela executou. Requer uma chave de API com escopo `full`. `GET /automations/{id}/runs/{run_id}` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). - `run_id` (string, obrigatório): O ID da execução (`aur_…`). ## Retorno Retorna a execução em `data` com os campos descritos em [Listar execuções](/pt/docs/api-reference/automations/runs/), além do `payload` e do `meta` completos e de um array `run_steps`. - `payload` (object | null): O payload do gatilho: os dados do evento (`{ "object": { … } }`) ou o payload que você passou para [Disparar uma execução](/pt/docs/api-reference/automations/trigger/), com `automation_id` adicionado. - `meta` (object | null): `source_event_id` vincula a execução ao evento que a iniciou. Execuções com falha podem ter `failure_reason`: `insufficient_credits` (não foi possível cobrar os 3 créditos da execução) ou `run_timeout` (a execução ainda estava `running` depois de 72 horas sem nenhuma etapa em espera). - `run_steps` (object[]): Uma entrada por etapa alcançada pela execução: - `step_id`: o ID da etapa (`aus_…`). Associe-o a `steps[].id` de [Obter uma automação](/pt/docs/api-reference/automations/get/). - `status`: `running`, `waiting` (uma etapa `wait` cujo tempo ainda não passou), `completed` ou `failed`. - `data`: o resultado da etapa. Por exemplo, `send_email` retorna `{ "result": "email_queued", "email_oid": "em_…", "to": "…" }`, `condition` retorna `{ "result": true, "branch": "yes" }` e as etapas com falha retornam `{ "error": "…" }`. - `started_at`, `completed_at`, `created_at`. Retorna `404` se a automação ou a execução não existir. **Requisição** `GET /automations/{id}/runs/{run_id}` **cURL** ```bash curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs/aur_3q6GdFk2eRSG093grI0v9e6REu8 \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch( 'https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs/aur_3q6GdFk2eRSG093grI0v9e6REu8', { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } }, ); const { data: run } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs/aur_3q6GdFk2eRSG093grI0v9e6REu8", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) run = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs/aur_3q6GdFk2eRSG093grI0v9e6REu8', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $run = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "id": "aur_3q6GdFk2eRSG093grI0v9e6REu8", "automation_id": "aut_3xqC9YD79FZZA36uTekWTBO1ghe", "contact_id": "con_3munwNLaXKUARc6ff9wPtxKVq4A", "email_id": null, "event_id": null, "event": "contact.added_to_audience", "payload": { "object": { "id": "sub_3Fh2pQx9LmZr4Wt7Nc0bVd8KsYe", "object": "subscriber", "subscribed": true, "audience": { "id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV", "name": "Newsletter" }, "contact": { "id": "con_3munwNLaXKUARc6ff9wPtxKVq4A", "email": "ada@example.com" } } }, "meta": { "source_event_id": "evt_3Kd8sWq1NzXc5Vb7Mt2LpRy0HgA" }, "status": "running", "started_at": "2026-10-03T14:12:40.551870+00:00", "completed_at": null, "created_at": "2026-10-03T14:12:40.551870+00:00", "updated_at": "2026-10-03T14:12:40.551870+00:00", "run_steps": [ { "step_id": "aus_3V5TZIXXak1SSmGcOmzPOeFaguQ", "status": "completed", "data": { "result": "email_queued", "outcome": "accepted", "email_oid": "em_3Cp8cMgPskzB8tIlgUyNJkpDp9O", "to": "ada@example.com" }, "started_at": "2026-10-03T14:12:40.702113+00:00", "completed_at": "2026-10-03T14:12:40.918540+00:00", "created_at": "2026-10-03T14:12:40.702113+00:00" }, { "step_id": "aus_3vM0ORwEXCQcyS7rylfQBQEXjVk", "status": "waiting", "data": { "status": "waiting", "delayMs": 86400000, "seconds": 86400 }, "started_at": "2026-10-03T14:12:41.004221+00:00", "completed_at": null, "created_at": "2026-10-03T14:12:41.004221+00:00" } ] } } ``` **404** ```json { "message": "Run not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/run/ ## Obter estatísticas — GET /automations/{id}/stats > Obtenha contagens por etapa de uma automação: quantas execuções chegaram a cada etapa, os status das etapas, os resultados e um funil de e-mail. # Obter estatísticas Retorna contagens de todas as etapas de uma automação, organizadas pela chave da etapa. Requer uma chave de API com escopo `full`. `GET /automations/{id}/stats` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). ## Parâmetros de consulta - `since` (string): Conta apenas as execuções de etapas criadas neste horário ou depois dele. Data e hora RFC 3339, por exemplo `2026-10-01T00:00:00Z`. - `until` (string): Conta apenas as execuções de etapas criadas neste horário ou antes dele. Data e hora RFC 3339. - `run_ids[]` (string): Conta apenas estas execuções (`aur_…`). Repita o parâmetro para várias execuções. ## Retorno Retorna `data`, um objeto com uma entrada por chave de etapa. As etapas que nenhuma execução alcançou têm `total` igual a `0`. - `total` (integer): Número de vezes que as execuções chegaram à etapa. - `by_status` (object): Contagens por status da etapa: `running`, `waiting`, `completed`, `failed`. - `by_outcome` (object): Contagens por resultado. `send_email` e `forward_email`: `accepted` e, depois, o estado mais recente do e-mail (`delivered`, `loaded`, `clicked`, `bounced`, `failed`, `complained`, `unsubscribed`, `canceled`). `condition`: `matched`, `not_matched`. `experiment`: a chave da variante escolhida. `call_webhook`: `2xx`, `4xx`, `5xx`, `timeout`, `network_error`. Etapas com falha: `error`. - `funnel` (object): Apenas para etapas `send_email`. Contagens cumulativas: `accepted` inclui todos os e-mails que avançaram mais, `delivered` inclui os e-mails carregados e clicados, e `loaded` inclui os clicados. `bounced`, `failed`, `complained` e `unsubscribed` são contagens simples. **Requisição** `GET /automations/{id}/stats` **cURL** ```bash curl -G https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stats \ -H "Authorization: Bearer $EMAILIT_API_KEY" \ -d since=2026-10-01T00:00:00Z ``` **Node.js** ```javascript const params = new URLSearchParams({ since: '2026-10-01T00:00:00Z' }); const res = await fetch( `https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stats?${params}`, { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } }, ); const { data: stats } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stats", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, params={"since": "2026-10-01T00:00:00Z"}, ) stats = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stats', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], 'query' => ['since' => '2026-10-01T00:00:00Z'], ]); $stats = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "joined": { "total": 0, "by_status": {}, "by_outcome": {} }, "welcome_email": { "total": 412, "by_status": { "completed": 409, "failed": 3 }, "by_outcome": { "delivered": 251, "loaded": 98, "clicked": 41, "bounced": 19, "error": 3 }, "funnel": { "accepted": 390, "delivered": 390, "loaded": 139, "clicked": 41, "bounced": 19, "failed": 0, "complained": 0, "unsubscribed": 0 } }, "wait_1_day": { "total": 409, "by_status": { "completed": 352, "waiting": 57 }, "by_outcome": {} }, "is_free_user": { "total": 352, "by_status": { "completed": 352 }, "by_outcome": { "matched": 270, "not_matched": 82 } }, "upgrade_tips": { "total": 270, "by_status": { "completed": 270 }, "by_outcome": { "accepted": 12, "delivered": 180, "loaded": 61, "clicked": 17 }, "funnel": { "accepted": 270, "delivered": 258, "loaded": 78, "clicked": 17, "bounced": 0, "failed": 0, "complained": 0, "unsubscribed": 0 } }, "done": { "total": 82, "by_status": { "completed": 82 }, "by_outcome": {} } } } ``` **404** ```json { "message": "Automation not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/stats/ ## Obter estatísticas das etapas — GET /automations/{id}/steps/{step_key}/stats > Obtenha as contagens de uma única etapa de automação pela chave dela: execuções, status, resultados e o funil de e-mail. # Obter estatísticas das etapas Retorna as contagens de uma etapa de uma automação. Requer uma chave de API com escopo `full`. Os campos são os mesmos de [Obter estatísticas](/pt/docs/api-reference/automations/stats/). `GET /automations/{id}/steps/{step_key}/stats` ## Parâmetros de caminho - `id` (string, obrigatório): O ID da automação (`aut_…`). - `step_key` (string, obrigatório): A `key` da etapa, por exemplo `welcome_email`. ## Parâmetros de consulta - `since` (string): Conta apenas as execuções de etapas criadas neste horário ou depois dele. Data e hora RFC 3339. - `until` (string): Conta apenas as execuções de etapas criadas neste horário ou antes dele. Data e hora RFC 3339. ## Retorno Retorna `data` com `total`, `by_status`, `by_outcome` e, para etapas `send_email`, `funnel`. Retorna `404` se a automação ou a chave da etapa não existir. **Requisição** `GET /automations/{id}/steps/{step_key}/stats` **cURL** ```bash curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/steps/welcome_email/stats \ -H "Authorization: Bearer $EMAILIT_API_KEY" ``` **Node.js** ```javascript const res = await fetch( 'https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/steps/welcome_email/stats', { headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` } }, ); const { data: stats } = await res.json(); ``` **Python** ```python import os, requests r = requests.get( "https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/steps/welcome_email/stats", headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"}, ) stats = r.json()["data"] ``` **PHP** ```php $client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']); $response = $client->get('automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/steps/welcome_email/stats', [ 'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')], ]); $stats = json_decode($response->getBody(), true)['data']; ``` **200** ```json { "data": { "total": 412, "by_status": { "completed": 409, "failed": 3 }, "by_outcome": { "delivered": 251, "loaded": 98, "clicked": 41, "bounced": 19, "error": 3 }, "funnel": { "accepted": 390, "delivered": 390, "loaded": 139, "clicked": 41, "bounced": 19, "failed": 0, "complained": 0, "unsubscribed": 0 } } } ``` **404** ```json { "message": "Step not found." } ``` --- Fonte: https://emailit.com/pt/docs/api-reference/automations/step-stats/