# Paginación

> Recorre los endpoints de listado de la API de Emailit con page y limit, lee next_page_url, gestiona los formatos per_page y offset y las ventanas de tiempo de los emails y los eventos.

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:

| Parámetro | Descripción |
| --- | --- |
| `page` | La página que se devuelve, empezando por `1`. Por defecto, `1`. |
| `limit` | Objetos por página, de `1` a `100`. Los valores fuera de ese rango devuelven un error de validación `400`. |

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

| `limit` por defecto | Endpoints |
| --- | --- |
| 10 | Dominios, claves de API, listas de contactos, contactos, campañas, formularios, direcciones bloqueadas, webhooks, listas de direcciones (verificación masiva) |
| 25 | Emails, suscriptores |
| 50 | Resultados de las listas de direcciones (verificación masiva) |
| 100 | Eventos |

[Listar suscriptores](/es/docs/api-reference/audiences/subscribers/list/) también acepta `per_page` como alias de `limit`.

### Respuesta

```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 | Descripción |
| --- | --- |
| `data` | Los objetos de esta página, de más reciente a más antiguo salvo que los [ordenes](/es/docs/api-reference/filtering/). |
| `next_page_url` | Ruta de la página siguiente, o `null` en la última página. |
| `previous_page_url` | Ruta de la página anterior, o `null` en la primera página. |

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`:

| Campo | Endpoints | Contiene |
| --- | --- | --- |
| `total_records` | Contactos, listas de contactos, campañas, formularios | El número de objetos que coinciden, sumando todas las páginas. |
| `usage` | Webhooks | `used` y `limit` (endpoints de webhook usados y permitidos en tu plan) y `filters_allowed`. |
| `usage` | Suscriptores | `used` y `limit` (suscriptores usados y permitidos en la lista) y el `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Dominios | Cuántos dominios de envío permite tu plan (`null` significa sin límite), cuántos tienes y el nombre del plan. |

## Page y per_page

[Listar plantillas](/es/docs/api-reference/templates/list/), [Listar automatizaciones](/es/docs/api-reference/automations/list/) y [Listar ejecuciones](/es/docs/api-reference/automations/runs/) usan `per_page` en lugar de `limit` y devuelven recuentos de páginas en lugar de URL de página:

| Parámetro | Descripción |
| --- | --- |
| `page` | La página que se devuelve, empezando por `1`. Por defecto, `1`. |
| `per_page` | Objetos por página, de `1` a `100`. Por defecto, `25`. |

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

| Parámetro | Descripción |
| --- | --- |
| `limit` | Filas que se devuelven. Informes: por defecto `25`, máximo `100`. Orígenes, países, redes y emisores de informes: por defecto `50`, máximo `200`. |
| `offset` | Filas que se saltan. Por defecto, `0`. |

[Listar informes agregados](/es/docs/api-reference/dmarc/list/) y [Listar informes forenses](/es/docs/api-reference/dmarc/forensic/) devuelven el recuento total, así que sabes cuándo parar:

```json
{
  "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](/es/docs/api-reference/emails/list/) 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](/es/docs/api-reference/events/list/) 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:

**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 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

  - [Filtrado y ordenación](/es/docs/api-reference/filtering/): Acota y ordena los resultados de las listas.
  - [Límites de velocidad](/es/docs/api-reference/rate-limits/): Mantén las lecturas masivas dentro de lo razonable.

---
Fuente: https://emailit.com/es/docs/api-reference/pagination/