# Eventos

> Navegue pelos eventos que o Emailit registra para o seu workspace no painel ou com a API de eventos e use-os para recuperar ou conciliar webhooks.

Um evento é um registro de que algo aconteceu no seu workspace: um e-mail foi entregue, um link foi clicado, uma mensagem chegou ao seu subdomínio de recebimento, um contato foi criado. O Emailit armazena todos os eventos, mostra-os no painel e monta todas as requisições de [webhook](/pt/docs/webhooks/) a partir deles. Esta página explica como navegar pelos eventos e lê-los com a API.

## O que um evento contém

| Campo | Descrição |
| --- | --- |
| `id` | O ID do evento, que começa com `evt_`. Nas requisições de webhook, ele se chama `event_id`. |
| `type` | O que aconteceu, por exemplo `email.delivered` ou `contact.created`. Consulte [Tipos de eventos](/pt/docs/webhooks/event-types/). |
| `data.object` | O recurso a que o evento se refere, como o e-mail, o clique, o domínio ou o contato, como ele estava quando o evento aconteceu. |
| `created_at` | Quando o evento foi registrado. |

```json
{
  "object": "event",
  "id": "evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_2xGk7Lr3XcB8pQ1wYzK4dTfG9hJ",
      "object": "email",
      "from": "billing@acme.com",
      "to": "ada@example.com",
      "subject": "Your receipt #1042",
      "status": "delivered",
      "meta": { "order_id": "1042" },
      "updated_at": "2026-10-01T09:14:03.512000+00:00",
      "created_at": "2026-10-01T09:14:01.207000+00:00"
    }
  },
  "created_at": "2026-10-01T09:14:03.540000+00:00"
}
```

## Eventos e webhooks

Os eventos são a origem das requisições de webhook. Quando o Emailit registra um evento, ele coloca na fila uma requisição para cada webhook ativado que esteja inscrito nesse tipo de evento e cujo [filtro de payload](/pt/docs/webhooks/set-up/#filter-events-by-payload) corresponda. O evento é armazenado mesmo que nenhum webhook o receba.

Isso tem duas consequências:

- Um webhook só recebe os eventos que acontecem enquanto ele existe e está ativado. Os eventos registrados enquanto um webhook estava desativado, ou antes de ele ser criado, não são enviados a ele depois.
- Você pode usar a lista de eventos para preencher lacunas. Depois de uma indisponibilidade ou de um período desativado, leia os eventos dessa janela de tempo com a API e processe os que o seu webhook perdeu. Elimine duplicados pelo ID do evento, que é o mesmo ID `evt_` que os webhooks usam como `event_id`.

## Navegar pelos eventos no painel

Acesse **Email API → Events**. A tabela mostra o tipo (**Event type**), o **ID** e o horário de criação (**Created**) de cada evento, dos mais recentes para os mais antigos.

- Por padrão, a página mostra os últimos 2 dias. Adicione um filtro **Created** para ver eventos mais antigos, dentro do seu período de retenção.
- Filtre por **Type** para ver um tipo de evento, por exemplo só `email.bounced`.
- Selecione um evento para ver o horário em **Created**, o **Type** e o **Payload** completo em JSON, com um botão de copiar.

## Ler eventos com a API

Os dois endpoints exigem uma chave de API **Full Access**.

### Listar eventos

[Listar eventos](/pt/docs/api-reference/events/list/) retorna os eventos dos mais recentes para os mais antigos.

| Parâmetro de consulta | Descrição |
| --- | --- |
| `type` | Um tipo, ou vários separados por vírgula, por exemplo `email.bounced,email.complained`. |
| `include_data` | `true` para incluir `data` em cada evento. O padrão é `false`, que retorna só `id`, `type` e `created_at`. |
| `page`, `limit` | Número e tamanho da página. `limit` vai de 1 a 100, e o padrão é 100. |
| `created_at.after`, `created_at.before` | Filtros de data. Consulte [Filtragem e ordenação](/pt/docs/api-reference/filtering/). |

```bash
curl -G https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  --data-urlencode "type=email.bounced,email.complained" \
  --data-urlencode "created_at.after=2026-09-28T00:00:00Z" \
  --data-urlencode "include_data=true"
```

```json
{
  "data": [
    {
      "object": "event",
      "id": "evt_2xGkB3n8WqZ5cT1vRmK7pLsD4hY",
      "type": "email.bounced",
      "data": { "object": { "id": "em_2xGkA9m1PdX6bR3sQnJ8tKfW2eV", "object": "email", "status": "bounced" } },
      "created_at": "2026-09-30T17:02:41.118000+00:00"
    }
  ],
  "next_page_url": "/v2/events?page=2&limit=100&type=email.bounced%2Cemail.complained&include_data=true",
  "previous_page_url": null
}
```

Dois limites mantêm este endpoint rápido:

- **Janela padrão.** Sem um filtro `created_at`, a lista cobre os últimos 2 dias. Adicione `created_at.after` para ler eventos mais antigos.
- **Profundidade das páginas.** O deslocamento, `(page - 1) × limit`, não pode passar de 2.500. Páginas mais profundas retornam `422` com o código `events_offset_too_large`. Restrinja a requisição com `type` ou com um intervalo de `created_at` em vez de avançar nas páginas.

### Obter um evento

[Obter um evento](/pt/docs/api-reference/events/get/) retorna um evento pelo ID `evt_` dele, sempre com `data`.

```bash
curl https://api.emailit.com/v2/events/evt_2xGk7Nq1VbD5sR8tLmW3eYhC6aP \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

## Conciliar eventos de webhook perdidos

1. **Escolha a janela.** Anote quando o seu endpoint começou a falhar ou quando o webhook foi desativado, e quando o problema foi corrigido.

2. **Liste os eventos.** Chame `GET /v2/events` com `created_at.after` e `created_at.before` definidos para essa janela, os valores de `type` que o seu webhook trata e `include_data=true`. Siga `next_page_url` até ele ser `null`. Se você receber `events_offset_too_large`, divida a janela em intervalos menores.

3. **Processe o que você ainda não viu.** Ignore os eventos cujo ID você já armazenou como processado e trate os demais com o mesmo código que o seu webhook usa.

Para requisições que foram colocadas na fila mas falharam, a opção [Retry failed](/pt/docs/webhooks/retries-and-failures/#retry-failed-requests) do webhook é mais simples, desde que as falhas tenham menos de 7 dias.

## Retenção

Os eventos seguem o período de retenção de **Logs**, o mesmo dos logs de requisições e das requisições de webhook:

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Retenção dos logs de requisições | 7 dias | 30 dias | 30 dias | Flexível |

## Veja também

  - [Tipos de eventos](/pt/docs/webhooks/event-types/)
  - [API de eventos](/pt/docs/api-reference/events/)

---
Fonte: https://emailit.com/pt/docs/logs/events/