Paginación

Los endpoints de listado devuelven los resultados página a página. La mayoría usan números de página con page y limit, las plantillas y las automatizaciones usan page y per_page, y los endpoints DMARC usan limit y offset. Esta página explica cada formato, las ventanas de tiempo de las listas de emails y de eventos, y cómo recorrer todas las páginas.

Page y limit

La mayoría de los endpoints de listado aceptan dos parámetros de consulta:

El tamaño de página por defecto depende del endpoint:

Listar suscriptores también acepta per_page como alias de limit.

Respuesta

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

Las URL de página son rutas, no URL completas, y en la mayoría de los endpoints solo llevan page y limit, no tus filtros. Para obtener la página siguiente, repite tu propia petición aumentando page en uno, y detente cuando next_page_url sea null.

Algunas listas añaden campos junto a data:

Page y per_page

Listar plantillas, Listar automatizaciones y Listar ejecuciones usan per_page en lugar de limit y devuelven recuentos de páginas en lugar de URL de página:

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

Sigue pidiendo páginas mientras current_page sea menor que total_pages.

Limit y offset

Los endpoints DMARC se saltan un número de filas en lugar de contar páginas:

Listar informes agregados y Listar informes forenses devuelven el recuento total, así que sabes cuándo parar:

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

Los endpoints de desglose devuelven meta solo con limit y offset. Detente cuando una página tenga menos filas que limit.

Ventanas de tiempo

Dos listas solo tienen en cuenta los datos recientes, salvo que pidas más:

• Emails. Listar emails devuelve por defecto los emails de los últimos 14 días. Pasa date_from (y, opcionalmente, date_to) como una fecha, por ejemplo 2026-08-01, para buscar más atrás. Los filtros created_at no amplían la ventana, así que usa date_from.
• Eventos. Listar eventos devuelve por defecto los eventos de los últimos dos días. Cualquier filtro created_at, como created_at.after=2026-09-01, sustituye esa ventana. La lista también se detiene en un desplazamiento de 2500: una página que empieza más allá del evento número 2500 devuelve 422 con el código events_offset_too_large. Acota los resultados con los filtros type o created_at para llegar a eventos más antiguos.

Obtener todas las páginas

Repite hasta que la API indique que no hay página siguiente. Estos ejemplos recopilan todos los contactos de una lista de contactos:

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 coherentes

Las páginas se calculan en el momento en que las pides. Si se crean o eliminan objetos mientras recorres una lista ordenada de más reciente a más antiguo, los objetos pueden cambiar de página, así que podrías ver uno dos veces o saltarte otro. Para obtener una exportación estable de una lista que no deja de crecer, ordena de más antiguo a más reciente con order=created_at&direction=asc (o sort=created_at&order=asc en los contactos y las direcciones bloqueadas) y omite los ID que ya hayas visto.

Ver también