Pular para o conteúdo
Docs

Automações

Monte fluxos com gatilhos e etapas, execute-os e inspecione as execuções.

URL basehttps://api.emailit.com/v2AutenticaçãoErrosLimites de requisições

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. 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

contextstringobrigató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.
namestringobrigatório
Nome da automação, com até 191 caracteres.
descriptionstring | null
Descrição opcional.
settingsobject
Regras de execução. Consulte Configurações.
stepsobject[]obrigatório
As etapas de gatilho e de ação, com pelo menos um gatilho. Consulte Etapas.
connectionsobject[]obrigatório
As arestas entre as etapas. Passe [] para um grafo que só tem um gatilho. Consulte Conexões.

Configurações

on_step_failurestringpadrão: stop
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_reentrybooleanpadrão: true
false ignora um gatilho quando o mesmo contato (ou e-mail) já tem uma execução em andamento nesta automação.
max_concurrent_runsintegerpadrão: 0
Número máximo de execuções com status running ao mesmo tempo. 0 significa sem limite.
cooldown_secondsintegerpadrão: 0
Ignora um gatilho quando o mesmo contato (ou e-mail) iniciou uma execução nesta automação dentro desse número de segundos.

Etapas

keystringobrigatório
O seu identificador da etapa, único dentro da automação, por exemplo welcome_email. As conexões, as estatísticas das etapas e as atualizações se referem às etapas pela chave.
typestringobrigatório
trigger ou action.
triggerstring
Nome do gatilho, obrigatório quando type é trigger. Consulte Gatilhos.
actionstring
Nome da ação, obrigatório quando type é action. Consulte Ações.
configobject
Configurações do gatilho ou da ação.

Conexões

fromstringobrigatório
Chave da etapa em que a aresta começa.
tostringobrigatório
Chave da próxima etapa.
branchstringpadrão: default
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.

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.<name> 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.
system.schedule todos Aceito, mas o Emailit ainda não dispara gatilhos agendados.

Campos de config dos gatilhos:

audience_idstring
Para contact.added_to_audience e contact.removed_from_audience: dispara apenas para esta lista de contatos (aud_…).
date_fieldstring
Para contact.date_anniversary e contact.on_date: a chave do campo personalizado que guarda a data, por exemplo birthday.
filterobject

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: <original subject>.
  • 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 verifica. Os erros retornam 400 com errors organizados pelo caminho do campo.

POST/automations
Terminal
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 <hello@acme.com>" }
      },
      {
        "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" }
    ]
  }'
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 <hello@acme.com>" }
      },
      {
        "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
}

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

idstringobrigatório
O ID da automação (aut_…).

Retorno

Retorna a automação em data.

idstring
ID da automação, com o prefixo aut_.
contextstring
contact, email ou event.
namestring
Nome da automação.
descriptionstring | null
Descrição opcional.
statusstring
draft, running, paused, stopped ou archived.
settingsobject
Regras de execução: on_step_failure, allow_reentry, max_concurrent_runs, cooldown_seconds. Vazio quando você não definiu nenhuma.
last_triggered_atstring | null
Quando a automação iniciou uma execução pela última vez.
published_atstring | null
Quando a automação foi iniciada pela primeira vez.
stepsobject[]
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.
connectionsobject[]
As chaves das etapas from e to de cada aresta e o branch dela.

Consulte Criar uma automação 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.

GET/automations/{id}
Terminal
curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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 <hello@acme.com>" }
      },
      {
        "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" }
    ]
  }
}

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 antes de alterar o grafo de uma automação em andamento e depois inicie-a de novo para que os novos gatilhos entrem em vigor.

POST/automations/{id}

Parâmetros de caminho

idstringobrigatório
O ID da automação (aut_…).

Parâmetros do corpo

namestring
Nome, com até 191 caracteres.
descriptionstring
Descrição.
settingsobject
Substitui todas as configurações: on_step_failure, allow_reentry, max_concurrent_runs, cooldown_seconds. Consulte Configurações.
stepsobject[]
A lista completa de etapas. Obrigatório quando você envia connections. Consulte Etapas.
connectionsobject[]
A lista completa de conexões. Obrigatório quando você envia steps. Consulte Conexões.

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.

POST/automations/{id}
Terminal
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" }
  }'
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 <hello@acme.com>" }
      }
    ],
    "connections": [
      { "from": "joined", "to": "welcome_email", "branch": "default" }
    ]
  },
  "message": "Automation was successfully updated.",
  "notify": true
}

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

pageintegerpadrão: 1
Número da página, a partir de 1.
per_pageintegerpadrão: 25
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.
sortstringpadrão: created_at
Campo de ordenação: name, created_at, updated_at ou last_triggered_at.
orderstringpadrão: desc
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.

Retorno

dataobject[]
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 para lê-lo.
total_recordsinteger
Número de automações que correspondem.
per_pageinteger
Tamanho de página usado.
current_pageinteger
O número desta página.
total_pagesinteger
Número de páginas.
GET/automations
Terminal
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
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
}

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 antes de excluí-la.

DELETE/automations/{id}

Parâmetros de caminho

idstringobrigató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.

DELETE/automations/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "message": "Automation was deleted successfully.",
  "notify": true
}

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, 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, 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

idstringobrigató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.

POST/automations/{id}/start
Terminal
curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/start \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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 <hello@acme.com>" }
      }
    ],
    "connections": [
      { "from": "joined", "to": "welcome_email", "branch": "default" }
    ]
  },
  "message": "Automation was successfully started.",
  "notify": true
}

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 em vez de pausá-la. Inicie-a de novo para retomar os disparos.

POST/automations/{id}/pause

Parâmetros de caminho

idstringobrigató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.

POST/automations/{id}/pause
Terminal
curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/pause \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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 <hello@acme.com>" }
      }
    ],
    "connections": [
      { "from": "joined", "to": "welcome_email", "branch": "default" }
    ]
  },
  "message": "Automation was successfully paused.",
  "notify": true
}

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 em vez de interrompê-la. Você pode iniciar de novo uma automação interrompida; as novas execuções começam do zero.

POST/automations/{id}/stop

Parâmetros de caminho

idstringobrigató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.

POST/automations/{id}/stop
Terminal
curl -X POST https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stop \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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 <hello@acme.com>" }
      }
    ],
    "connections": [
      { "from": "joined", "to": "welcome_email", "branch": "default" }
    ]
  },
  "message": "Automation was successfully stopped.",
  "notify": true
}

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.

POST/automations/{id}/trigger

Parâmetros de caminho

idstringobrigatório
O ID da automação (aut_…).

Parâmetros do corpo

payloadobject

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.

POST/automations/{id}/trigger
Terminal
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"
    }
  }'
JSON
{
  "message": "Automation trigger dispatched."
}

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

idstringobrigatório
O ID da automação (aut_…).

Parâmetros de consulta

pageintegerpadrão: 1
Número da página, a partir de 1.
per_pageintegerpadrão: 25
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.

Retorno

dataobject[]
As execuções desta página. Veja os campos abaixo.
total_records, per_page, current_page, total_pagesinteger
Detalhes da paginação.

Cada execução tem:

idstring
ID da execução, com o prefixo aur_.
automation_idstring
A automação (aut_…).
contact_idstring | null
O contato da execução (con_…) no contexto contact.
email_idstring | null
O e-mail da execução (em_…) no contexto email.
event_idstring | null
ID do evento de origem, quando o payload do gatilho tiver um.
eventstring
O gatilho que iniciou a execução, por exemplo contact.added_to_audience ou system.manual.
payloadobject
Sempre um objeto vazio nesta listagem. Obtenha a execução para ler o payload do gatilho.
metaobject
Sempre um objeto vazio nesta listagem. Obtenha a execução para ler os metadados dela, como failure_reason.
statusstring
running, completed, failed ou canceled (a automação foi interrompida).
started_at, completed_at, created_at, updated_atstring | null
Timestamps em UTC.
GET/automations/{id}/runs
Terminal
curl -G https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "filter[status]=failed"
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
}

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

idstringobrigatório
O ID da automação (aut_…).
run_idstringobrigatório
O ID da execução (aur_…).

Retorno

Retorna a execução em data com os campos descritos em Listar execuções, além do payload e do meta completos e de um array run_steps.

payloadobject | null
O payload do gatilho: os dados do evento ({ "object": { … } }) ou o payload que você passou para Disparar uma execução, com automation_id adicionado.
metaobject | 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_stepsobject[]

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.
  • 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.

GET/automations/{id}/runs/{run_id}
Terminal
curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/runs/aur_3q6GdFk2eRSG093grI0v9e6REu8 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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"
      }
    ]
  }
}

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

idstringobrigatório
O ID da automação (aut_…).

Parâmetros de consulta

sincestring
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.
untilstring
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.

totalinteger
Número de vezes que as execuções chegaram à etapa.
by_statusobject
Contagens por status da etapa: running, waiting, completed, failed.
by_outcomeobject
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.
funnelobject
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.
GET/automations/{id}/stats
Terminal
curl -G https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/stats \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d since=2026-10-01T00:00:00Z
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": {}
    }
  }
}

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.

GET/automations/{id}/steps/{step_key}/stats

Parâmetros de caminho

idstringobrigatório
O ID da automação (aut_…).
step_keystringobrigatório
A key da etapa, por exemplo welcome_email.

Parâmetros de consulta

sincestring
Conta apenas as execuções de etapas criadas neste horário ou depois dele. Data e hora RFC 3339.
untilstring
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.

GET/automations/{id}/steps/{step_key}/stats
Terminal
curl https://api.emailit.com/v2/automations/aut_3xqC9YD79FZZA36uTekWTBO1ghe/steps/welcome_email/stats \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
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
    }
  }
}

Esta página foi útil?

Obrigado pelo feedback.

Obrigado, lemos todas as mensagens.

Esc

Populares

↑↓para navegar↵para abrirEscpara fechar