Eventos

Envie eventos do workspace e eventos personalizados, e consulte o fluxo de eventos por trás dos webhooks: entregas, bounces, aberturas e mais.

URL basehttps://api.emailit.com/v2Autenticação Erros Limites de requisições

POST/events
POST/events/batch
GET/events
GET/events/{id}

Enviar um evento

Registra um evento do workspace (w:<name>) ou um evento personalizado (c:<name>). Funciona com chaves de API com escopo full ou events. Consulte Rastreamento de eventos para saber quando usar cada um. Os eventos estão incluídos nos planos Pro, Business e Custom, com até 100 tipos de evento no Pro e 1.000 no Business.

Um evento do workspace precisa ser definido antes. As properties dele são verificadas em relação à definição.
Um evento personalizado não precisa de definição. As properties dele podem ser qualquer objeto JSON.

Os eventos do sistema, como email.delivered, são registrados pelo Emailit e não podem ser enviados. Para registrar muitos eventos em uma única chamada, use Enviar eventos em lote.

POST/events

Parâmetros do corpo

typestringobrigatório

w:<name> para um evento do workspace ou c:<name> para um evento personalizado, por exemplo, c:order.completed. O nome tem de 1 a 100 letras, dígitos, ., - ou _, e começa com uma letra ou um dígito.

propertiesobject

Os dados do evento. Padrão {}.

Eventos do workspace: apenas as propriedades da definição, cada uma com o seu tipo. As propriedades obrigatórias precisam estar presentes, null deixa uma propriedade opcional vazia, e as datas são armazenadas em ISO 8601, em UTC. Consulte Tipos de propriedade.
Eventos personalizados: qualquer objeto JSON, com até 32 KB e 8 níveis de profundidade.

emailstring

O endereço de e-mail da pessoa a quem o evento se refere. Se um contato tiver esse endereço, o evento é atribuído a esse contato. Se nenhum tiver, o endereço é armazenado mesmo assim, e o evento aparece na atividade do contato quando você criar um.

contact_idstring

O ID de um contato existente (con_…). Tem precedência sobre email. Um ID que não corresponda a um contato do workspace retorna 422.

anonymous_idstring

O seu próprio identificador para um visitante ou dispositivo, com até 128 caracteres, para eventos que você ainda não consegue vincular a uma pessoa.

occurred_atstring | integer

Quando aconteceu: uma data e hora ISO 8601 ou um timestamp em milissegundos. Padrão: agora. Pode estar no passado, mas não mais de 24 horas no futuro.

contextobject

Onde o evento aconteceu: page (url, path, title, referrer, search), campaign (source, medium, name, term, content), locale e timezone. As chaves desconhecidas são descartadas e os valores longos são encurtados.

Os contatos são apenas procurados, nunca criados. O Emailit não armazena endereços IP com os eventos.

Retorno

Retorna 201 Created com o evento: object, id, type, created_at e data. data.object contém o que foi armazenado:

objectstring

workspace_event ou custom_event.

namestring

O nome do evento, sem o prefixo.

propertiesobject

As propriedades validadas.

contactobject | null

id e email do contato ao qual o evento pertence. id é null quando apenas o e-mail é conhecido. null quando você não enviou nenhum dos dois.

anonymous_idstring | null

O anonymous_id que você enviou.

occurred_atstring

Quando aconteceu, em UTC.

sourcestring

api para este endpoint. Os eventos do script de rastreamento têm js, e os eventos de teste enviados pelo painel têm dashboard.

contextobject

O contexto armazenado. Omitido quando não há nenhum.

Uma chave de API com escopo events não pode ler dados, então ela recebe o evento de volta sem o data, que contém o contato encontrado pelo e-mail.

Status	Quando
`400`	O corpo não é um objeto JSON.
`403`	O escopo da chave de API não é `full` nem `events`, ou o plano não inclui eventos do workspace e personalizados: no Pay as you go, `error` é `plan_required` e `required_plan` é `pro`. Nada é armazenado.
`422`	O evento é inválido. `errors` é indexado por campo, como `type` ou `properties.total`, e `message` repete o primeiro problema. Também é retornado para um evento `w:` que não está definido, para um `contact_id` que não corresponde a um contato e para um tipo que o workspace nunca enviou quando ele já usa o número de tipos de evento do plano (100 no Pro, 1.000 no Business).
`429`	Muitas requisições em um minuto, ou o workspace atingiu o limite diário de uso justo para eventos do workspace e personalizados (`code`: `events_daily_limit`). Nada é armazenado. Tente de novo depois do número de segundos indicado no cabeçalho `retry-after`.

POST/events

Terminal

curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'c:order.completed',
    email: 'jane@example.com',
    properties: { order_id: '1001', total: 59.9, currency: 'EUR' },
    occurred_at: '2026-10-19T09:30:00Z',
  }),
});
const event = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "type": "c:order.completed",
        "email": "jane@example.com",
        "properties": {"order_id": "1001", "total": 59.9, "currency": "EUR"},
        "occurred_at": "2026-10-19T09:30:00Z",
    },
)
event = r.json()

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'type' => 'c:order.completed',
        'email' => 'jane@example.com',
        'properties' => ['order_id' => '1001', 'total' => 59.9, 'currency' => 'EUR'],
        'occurred_at' => '2026-10-19T09:30:00Z',
    ],
]);
$event = json_decode($response->getBody(), true);

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00",
  "data": {
    "object": {
      "object": "custom_event",
      "name": "order.completed",
      "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
      "contact": { "id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "email": "jane@example.com" },
      "anonymous_id": null,
      "occurred_at": "2026-10-19T09:30:00.000Z",
      "source": "api"
    }
  }
}

JSON

{
  "object": "event",
  "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF",
  "type": "c:order.completed",
  "created_at": "2026-10-19T09:30:02.114000+00:00"
}

JSON

{
  "error": "plan_required",
  "required_plan": "pro",
  "message": "Workspace and custom events are included with Pro and Business."
}

JSON

{
  "error": "properties.segment must be a string",
  "message": "properties.segment must be a string",
  "errors": {
    "properties.segment": ["must be a string"]
  }
}

JSON

{
  "error": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "message": "type w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier).",
  "errors": {
    "type": ["w:customer.tier is not defined in this workspace. Create it under /v2/workspace/events first, or send it as a custom event (c:customer.tier)."]
  }
}

Enviar eventos em lote

Registra até 100 eventos do workspace e eventos personalizados em uma única requisição, por exemplo, quando o seu backend sincroniza pedidos periodicamente. Funciona com chaves de API com escopo full ou events, nos planos Pro, Business e Custom.

O lote é tudo ou nada. Se algum evento for inválido, nenhum é armazenado, e a resposta lista cada problema pela posição do evento na lista.

POST/events/batch

Parâmetros do corpo

eventsobject[]obrigatório

De 1 a 100 eventos. Cada um aceita os mesmos campos de Enviar um evento: type, properties, email, contact_id, anonymous_id, occurred_at e context.

Retorno

Retorna 201 Created com os eventos armazenados em data, na ordem em que você os enviou. Cada item tem object (event), id, type e created_at. Use Obter um evento para ler um deles com o data.

Status	Quando
`400`	`events` está ausente, vazio ou tem mais de 100 itens.
`403`	O escopo da chave de API não é `full` nem `events`, ou o plano não inclui eventos do workspace e personalizados: no Pay as you go, `error` é `plan_required` e `required_plan` é `pro`. Nada é armazenado.
`422`	Pelo menos um evento é inválido. Nada é armazenado. `errors` é indexado por `events.<index>.<field>`, por exemplo, `events.3.properties.total`, contando a partir de 0, e `message` repete o primeiro problema. Um evento de um tipo que o workspace nunca enviou é inválido quando o workspace já usa o número de tipos de evento do plano (100 no Pro, 1.000 no Business).
`429`	Muitas requisições em um minuto, ou o lote levaria o workspace a ultrapassar o limite diário de uso justo para eventos do workspace e personalizados (`code`: `events_daily_limit`). Nada é armazenado. Tente de novo depois do número de segundos indicado no cabeçalho `retry-after`.

POST/events/batch

Terminal

curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } },
      { "type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": { "segment": "b2b" } }
    ]
  }'

JavaScript

const res = await fetch('https://api.emailit.com/v2/events/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      { type: 'c:order.completed', email: 'jane@example.com', properties: { order_id: '1001', total: 59.9 } },
      { type: 'c:order.completed', email: 'omar@example.com', properties: { order_id: '1002', total: 18 } },
      { type: 'w:customer.type', contact_id: 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', properties: { segment: 'b2b' } },
    ],
  }),
});
const { data } = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.emailit.com/v2/events/batch",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "events": [
            {"type": "c:order.completed", "email": "jane@example.com", "properties": {"order_id": "1001", "total": 59.9}},
            {"type": "c:order.completed", "email": "omar@example.com", "properties": {"order_id": "1002", "total": 18}},
            {"type": "w:customer.type", "contact_id": "con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9", "properties": {"segment": "b2b"}},
        ]
    },
)
stored = r.json()["data"]

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('events/batch', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'events' => [
            ['type' => 'c:order.completed', 'email' => 'jane@example.com', 'properties' => ['order_id' => '1001', 'total' => 59.9]],
            ['type' => 'c:order.completed', 'email' => 'omar@example.com', 'properties' => ['order_id' => '1002', 'total' => 18]],
            ['type' => 'w:customer.type', 'contact_id' => 'con_2wPq7Lm3XcN8bV1zKd4RtY6sHf9', 'properties' => ['segment' => 'b2b']],
        ],
    ],
]);
$stored = json_decode($response->getBody(), true)['data'];

JSON

{
  "data": [
    { "object": "event", "id": "evt_2yJm3Rk8VbN1sQ5tLwX7eZhD4cF", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Sa1XcP4uW8rMyB6fGjK0nT", "type": "c:order.completed", "created_at": "2026-10-19T09:30:02.114000+00:00" },
    { "object": "event", "id": "evt_2yJm3Td5ZeQ7vX2sNzC9hHkL3pU", "type": "w:customer.type", "created_at": "2026-10-19T09:30:02.114000+00:00" }
  ]
}

JSON

{
  "error": "events.1.email must be a valid email address",
  "message": "events.1.email must be a valid email address",
  "errors": {
    "events.1.email": ["must be a valid email address"],
    "events.2.properties.segment": ["must be a string"]
  }
}

Listar eventos

Retorna os eventos do seu workspace, dos mais recentes para os mais antigos. Cada entrega de webhook é montada a partir de um desses eventos, então você pode usar este endpoint para recuperar os eventos que o seu endpoint perdeu. Requer uma chave de API com escopo full.

GET/events

Parâmetros de consulta

pageinteger

Número da página, a partir de 1. Padrão 1. Páginas além de 2.500 eventos ((page - 1) × limit > 2500) retornam 422.

limitinteger

Eventos por página, de 1 a 100. Padrão 100.

typestring

Tipo de evento, ou uma lista de tipos separados por vírgulas, por exemplo email.delivered,email.bounced. Os eventos do workspace e os eventos personalizados mantêm o prefixo, por exemplo c:order.completed. Consulte Tipos de evento.

scopestring

Apenas eventos destes escopos, separados por vírgulas: system (eventos que o Emailit registra, como email.delivered), workspace (eventos definidos no workspace, w:<name>) e custom (eventos personalizados, c:<name>). Por exemplo, scope=workspace,custom. Padrão: todos os escopos. Um escopo desconhecido retorna 400.

include_databoolean

Defina como true para incluir o payload data de cada evento. Padrão false, que retorna apenas object, id, type e created_at.

matchstring

all (padrão) exige todos os filtros. or corresponde a qualquer filtro. Consulte Filtragem.

orderstring

Chave de ordenação desta lista. Consulte as chaves de ordenação abaixo.

directionstring

asc ou desc.

Filtros e ordenação

Os filtros de listagem são um único nível de parâmetros de consulta key.condition=value. Consulte Filtragem para match, order, direction e a lista de condições por tipo.

Chaves de filtro

Chave	Tipo	Condições	Observações
`type`	string	exact, not_exact, contains, not_contains, starts_with, ends_with, empty, not_empty
`created_at`	date	exact, before, after, empty, not_empty

Chaves de ordenação

Passe em order uma destas chaves e em direction o valor asc ou desc: type, created_at

Sem um filtro created_at, a lista cobre apenas os últimos 2 dias. Para ir mais para trás, adicione um, por exemplo created_at.after=2026-09-01T00:00:00Z. Os eventos mais antigos ficam disponíveis enquanto a retenção de dados do seu plano os mantiver.

Retorno

Retorna 200 OK com os eventos em data, além de next_page_url e previous_page_url (null nas extremidades). As URLs de página mantêm type, scope, limit e include_data.

Retorna 422 com code: "events_offset_too_large" quando a página é profunda demais. Restrinja o intervalo de datas ou os tipos em vez de continuar paginando.

GET/events

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const events = await emailit.events.list({ type: 'email.delivered' });

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

events = client.events.list({"type": "email.delivered"})

PHP

$emailit = Emailit::client('your_api_key');

$events = $emailit->events()->list(['type' => 'email.delivered']);

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

events = client.events.list(type: "email.delivered")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

events, err := client.Events.List(&emailit.ListEventsRequest{Type: "email.delivered"})

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let events = emailit.events.list(Some(emailit::types::ListEventsParams { r#type: Some("email.delivered".into()), ..Default::default() })).await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject events = emailit.events().list();

using Emailit;

var emailit = new EmailitClient("your_api_key");

var events = emailit.Events.List(new EventListOptions { Type = "email.delivered" });

PHP

use Emailit\Laravel\Facades\Emailit;

$events = Emailit::events()->list(['type' => 'email.delivered']);

Terminal

curl -X GET "https://api.emailit.com/v2/events?type=email.delivered" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered",
  "previous_page_url": null
}

JSON

{
  "data": [
    {
      "object": "event",
      "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
      "type": "email.delivered",
      "data": {
        "object": {
          "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
          "object": "email",
          "from": "hello@acme.com",
          "to": "ada@example.com",
          "subject": "Your order has shipped",
          "status": "delivered",
          "meta": { "order_id": "1042" },
          "updated_at": "2026-10-01T10:02:14.307000+00:00",
          "created_at": "2026-10-01T10:02:11.583000+00:00"
        }
      },
      "created_at": "2026-10-01T10:02:15.912000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.delivered&include_data=true",
  "previous_page_url": null
}

JSON

{
  "error": "Page is too deep. Narrow the type or date filter, or open an earlier page.",
  "code": "events_offset_too_large"
}

Obter um evento

Retorna um evento com o payload data completo. O id é o mesmo valor que os webhooks enviam como event_id, então você pode consultar qualquer evento que recebeu. Requer uma chave de API com escopo full.

GET/events/:id

Parâmetros de caminho

idstringObrigatório

ID do evento, por exemplo evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a.

Retorno

Retorna 200 OK com o evento: object (event), id, type, data e created_at. data.object tem o mesmo formato que no payload de webhook desse tipo; consulte a referência de eventos de webhook.

Nos eventos do workspace (w:) e nos eventos personalizados (c:), data.object contém object (workspace_event ou custom_event), name, properties, contact, anonymous_id, occurred_at, source, identity_verified nos eventos do script de rastreamento que indicam um contato e, quando houver, context. Consulte Enviar um evento.

Retorna 404 com error: "Event not found" se o ID não existir no seu workspace.

GET/events/{id}

JavaScript

import { Emailit } from '@emailit/node';
const emailit = new Emailit('your_api_key');

const event = await emailit.events.get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Python

from emailit import EmailitClient
client = EmailitClient("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

PHP

$emailit = Emailit::client('your_api_key');

$event = $emailit->events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Ruby

require "emailit"
client = Emailit::EmailitClient.new("your_api_key")

event = client.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

import "github.com/emailit/emailit-go/v2"
client := emailit.NewClient("your_api_key")

event, err := client.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a")

Rust

use emailit::Emailit;
let emailit = Emailit::new("your_api_key");

let event = emailit.events.get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a").await?;

Java

import com.emailit.*;
import com.emailit.params.*;

EmailitClient emailit = new EmailitClient("your_api_key");

EmailitObject event = emailit.events().get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

using Emailit;

var emailit = new EmailitClient("your_api_key");

var ev = emailit.Events.Get("evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a");

PHP

use Emailit\Laravel\Facades\Emailit;

$event = Emailit::events()->get('evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a');

Terminal

curl https://api.emailit.com/v2/events/evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a \
  -H "Authorization: Bearer your_api_key"

JSON

{
  "object": "event",
  "id": "evt_2xLc9Rr4Tn6Wb1Qm8Ks3Vf0Hd7a",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xLc8Mm3Pq5Vn0Ra7Jt2Wd9Fb4e",
      "object": "email",
      "from": "hello@acme.com",
      "to": "ada@example.com",
      "subject": "Your order has shipped",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T10:02:14.307000+00:00",
      "created_at": "2026-10-01T10:02:11.583000+00:00"
    }
  },
  "created_at": "2026-10-01T10:02:15.912000+00:00"
}

JSON

{
  "error": "Event not found"
}