# Paginação

> Percorra os endpoints de listagem da API do Emailit com page e limit, leia next_page_url, trate os formatos per_page e offset e as janelas de tempo das listas de e-mails e eventos.

Os endpoints de listagem retornam os resultados uma página por vez. A maioria usa números de página com `page` e `limit`, templates e automações usam `page` e `per_page`, e os endpoints DMARC usam `limit` e `offset`. Esta página explica cada formato, as janelas de tempo das listas de e-mails e de eventos e como percorrer todas as páginas.

## Page e limit

A maioria dos endpoints de listagem aceita dois parâmetros de consulta:

| Parâmetro | Descrição |
| --- | --- |
| `page` | A página a retornar, a partir de `1`. Padrão `1`. |
| `limit` | Objetos por página, de `1` a `100`. Valores fora desse intervalo retornam um erro de validação `400`. |

O tamanho de página padrão depende do endpoint:

| `limit` padrão | Endpoints |
| --- | --- |
| 10 | Domínios, chaves de API, listas de contatos, contatos, campanhas, formulários, supressões, webhooks, listas de verificação de e-mails |
| 25 | E-mails, inscritos |
| 50 | Resultados das listas de verificação de e-mails |
| 100 | Eventos |

[Listar inscritos](/pt/docs/api-reference/audiences/subscribers/list/) também aceita `per_page` como alias de `limit`.

### Resposta

```json
{
  "data": [
    { "object": "domain", "id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey", "name": "acme.com" }
  ],
  "next_page_url": "/v2/domains?page=3&limit=10",
  "previous_page_url": "/v2/domains?page=1&limit=10"
}
```

| Campo | Descrição |
| --- | --- |
| `data` | Os objetos desta página, dos mais recentes para os mais antigos, a menos que você os [ordene](/pt/docs/api-reference/filtering/). |
| `next_page_url` | Caminho da próxima página, ou `null` na última página. |
| `previous_page_url` | Caminho da página anterior, ou `null` na primeira página. |

As URLs de página são caminhos, não URLs completas, e na maioria dos endpoints levam apenas `page` e `limit`, sem os seus filtros. Para buscar a próxima página, repita a sua própria requisição com `page` aumentado em um e pare quando `next_page_url` for `null`.

Algumas listas adicionam campos ao lado de `data`:

| Campo | Endpoints | Contém |
| --- | --- | --- |
| `total_records` | Contatos, listas de contatos, campanhas, formulários | O número de objetos que correspondem, em todas as páginas. |
| `usage` | Webhooks | `used` e `limit` de endpoints de webhook do seu plano, e `filters_allowed`. |
| `usage` | Inscritos | `used` e `limit` de inscritos da lista de contatos, e o `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Domínios | Quantos domínios de envio o seu plano permite (`null` significa sem limite), quantos você tem e o nome do plano. |

## Page e per_page

[Listar templates](/pt/docs/api-reference/templates/list/), [Listar automações](/pt/docs/api-reference/automations/list/) e [Listar execuções](/pt/docs/api-reference/automations/runs/) usam `per_page` em vez de `limit` e retornam contagens de páginas em vez de URLs de página:

| Parâmetro | Descrição |
| --- | --- |
| `page` | A página a retornar, a partir de `1`. Padrão `1`. |
| `per_page` | Objetos por página, de `1` a `100`. Padrão `25`. |

```json
{
  "data": [],
  "total_records": 42,
  "per_page": 25,
  "current_page": 2,
  "total_pages": 2
}
```

Continue pedindo páginas enquanto `current_page` for menor que `total_pages`.

## Limit e offset

Os endpoints DMARC pulam um número de linhas em vez de contar páginas:

| Parâmetro | Descrição |
| --- | --- |
| `limit` | Linhas a retornar. Relatórios: padrão `25`, máximo `100`. Fontes, países, redes e emissores: padrão `50`, máximo `200`. |
| `offset` | Linhas a pular. Padrão `0`. |

[Listar relatórios agregados](/pt/docs/api-reference/dmarc/list/) e [Listar relatórios forenses](/pt/docs/api-reference/dmarc/forensic/) retornam a contagem total, para que você saiba quando parar:

```json
{
  "data": [],
  "meta": { "total": 130, "limit": 25, "offset": 50 }
}
```

Os endpoints de detalhamento retornam `meta` apenas com `limit` e `offset`. Pare quando uma página tiver menos linhas que `limit`.

## Janelas de tempo

Duas listas só consideram dados recentes, a menos que você peça mais:

- **E-mails.** [Listar e-mails](/pt/docs/api-reference/emails/list/) retorna por padrão os e-mails dos últimos 14 dias. Passe `date_from` (e, opcionalmente, `date_to`) como uma data, por exemplo `2026-08-01`, para pesquisar mais para trás. Os filtros `created_at` não ampliam a janela, então use `date_from`.
- **Eventos.** [Listar eventos](/pt/docs/api-reference/events/list/) retorna por padrão os eventos dos últimos dois dias. Qualquer filtro `created_at`, como `created_at.after=2026-09-01`, substitui essa janela. A lista também para no offset 2.500: uma página que começa depois do 2.500º evento retorna `422` com o código `events_offset_too_large`. Restrinja os resultados com filtros `type` ou `created_at` para chegar a eventos mais antigos.

## Buscar todas as páginas

Repita até a API indicar que não há próxima página. Estes exemplos coletam todos os contatos de uma lista de contatos:

**cURL**

```bash
page=1
while : ; do
  response=$(curl -s -G https://api.emailit.com/v2/contacts \
    -H "Authorization: Bearer $EMAILIT_API_KEY" \
    --data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
    --data-urlencode "limit=100" \
    --data-urlencode "page=$page")

  echo "$response" | jq -c '.data[]'

  [ "$(echo "$response" | jq -r '.next_page_url')" = "null" ] && break
  page=$((page + 1))
done
```

**Node.js**

```javascript
async function* listAll(path, params = {}) {
  for (let page = 1; ; page++) {
    const query = new URLSearchParams({ ...params, limit: '100', page: String(page) });
    const response = await fetch(`https://api.emailit.com/v2${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Emailit ${response.status}`);

    const body = await response.json();
    yield* body.data;
    if (!body.next_page_url) return;
  }
}

for await (const contact of listAll('/contacts', { audience_id: 'aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2' })) {
  console.log(contact.email);
}
```

**Python**

```python
import os
import requests

def list_all(path, params=None):
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {os.environ['EMAILIT_API_KEY']}"
    page = 1
    while True:
        response = session.get(
            f"https://api.emailit.com/v2{path}",
            params={**(params or {}), "limit": 100, "page": page},
            timeout=30,
        )
        response.raise_for_status()
        body = response.json()
        yield from body["data"]
        if not body["next_page_url"]:
            return
        page += 1

for contact in list_all("/contacts", {"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"}):
    print(contact["email"])
```

## Resultados consistentes

As páginas são calculadas quando você as solicita. Se objetos forem criados ou excluídos enquanto você percorre uma lista ordenada dos mais recentes para os mais antigos, os objetos podem mudar de página, e você pode ver um deles duas vezes ou deixar de ver outro. Para uma exportação estável de uma lista que continua crescendo, ordene dos mais antigos para os mais recentes com `order=created_at&direction=asc` (ou `sort=created_at&order=asc` em contatos e supressões) e ignore os IDs que você já viu.

## Veja também

  - [Filtragem e ordenação](/pt/docs/api-reference/filtering/): Restrinja e ordene os resultados das listagens.
  - [Limites de requisições](/pt/docs/api-reference/rate-limits/): Mantenha as leituras em massa dentro do razoável.

---
Fonte: https://emailit.com/pt/docs/api-reference/pagination/