Paginação

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:

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

Listar inscritos também aceita per_page como alias de limit.

Resposta

{
  "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"
}

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:

Page e per_page

Listar templates, Listar automações e Listar execuções usam per_page em vez de limit e retornam contagens de páginas em vez de URLs de página:

{
  "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:

Listar relatórios agregados e Listar relatórios forenses retornam a contagem total, para que você saiba quando parar:

{
  "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 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 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:

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

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);
}

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