# Paginazione

> Scorri le pagine degli endpoint di elenco dell’API di Emailit con page e limit, leggi next_page_url, gestisci i formati per_page e offset e gli intervalli di tempo degli elenchi di email ed eventi.

Gli endpoint di elenco restituiscono i risultati una pagina alla volta. La maggior parte usa i numeri di pagina con `page` e `limit`, i template e le automazioni usano `page` e `per_page`, e gli endpoint DMARC usano `limit` e `offset`. Questa pagina spiega ciascun formato, gli intervalli di tempo degli elenchi di email ed eventi e come scorrere tutte le pagine.

## Page e limit

La maggior parte degli endpoint di elenco accetta due parametri di query:

| Parametro | Descrizione |
| --- | --- |
| `page` | La pagina da restituire, a partire da `1`. Predefinito `1`. |
| `limit` | Oggetti per pagina, da `1` a `100`. I valori fuori da questo intervallo restituiscono un errore di convalida `400`. |

La dimensione di pagina predefinita dipende dall’endpoint:

| `limit` predefinito | Endpoint |
| --- | --- |
| 10 | Domini, chiavi API, liste, contatti, campagne, moduli, soppressioni, webhook, liste di verifica |
| 25 | Email, iscritti |
| 50 | Esiti delle liste di verifica |
| 100 | Eventi |

[Elenca gli iscritti](/it/docs/api-reference/audiences/subscribers/list/) accetta anche `per_page` come alias di `limit`.

### Risposta

```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 | Descrizione |
| --- | --- |
| `data` | Gli oggetti di questa pagina, a partire dal più recente, a meno che tu non li [ordini](/it/docs/api-reference/filtering/) diversamente. |
| `next_page_url` | Il percorso della pagina successiva, oppure `null` sull’ultima pagina. |
| `previous_page_url` | Il percorso della pagina precedente, oppure `null` sulla prima pagina. |

Gli URL delle pagine sono percorsi, non URL completi, e sulla maggior parte degli endpoint riportano solo `page` e `limit`, non i tuoi filtri. Per recuperare la pagina successiva, ripeti la tua richiesta con `page` aumentato di uno e fermati quando `next_page_url` è `null`.

Alcuni elenchi aggiungono campi accanto a `data`:

| Campo | Endpoint | Contiene |
| --- | --- | --- |
| `total_records` | Contatti, liste, campagne, moduli | Il numero di oggetti corrispondenti, su tutte le pagine. |
| `usage` | Webhook | `used` e `limit` degli endpoint webhook del piano, e `filters_allowed`. |
| `usage` | Iscritti | `used` e `limit` degli iscritti della lista, e il `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Domini | Quanti domini di invio consente il piano (`null` significa nessun limite), quanti ne hai e il nome del piano. |

## Page e per_page

[Elenca i template](/it/docs/api-reference/templates/list/), [Elenca le automazioni](/it/docs/api-reference/automations/list/) ed [Elenca le esecuzioni](/it/docs/api-reference/automations/runs/) usano `per_page` invece di `limit` e restituiscono il numero di pagine invece degli URL delle pagine:

| Parametro | Descrizione |
| --- | --- |
| `page` | La pagina da restituire, a partire da `1`. Predefinito `1`. |
| `per_page` | Oggetti per pagina, da `1` a `100`. Predefinito `25`. |

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

Continua a richiedere pagine finché `current_page` è minore di `total_pages`.

## Limit e offset

Gli endpoint DMARC saltano un certo numero di righe invece di contare le pagine:

| Parametro | Descrizione |
| --- | --- |
| `limit` | Righe da restituire. Report: predefinito `25`, massimo `100`. Sorgenti, paesi, reti e mittenti dei report: predefinito `50`, massimo `200`. |
| `offset` | Righe da saltare. Predefinito `0`. |

[Elenca i report aggregati](/it/docs/api-reference/dmarc/list/) ed [Elenca i report forensi](/it/docs/api-reference/dmarc/forensic/) restituiscono il conteggio totale, così sai quando fermarti:

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

Gli endpoint di ripartizione restituiscono `meta` solo con `limit` e `offset`. Fermati quando una pagina ha meno righe di `limit`.

## Intervalli di tempo

Due elenchi considerano solo i dati recenti, a meno che tu non chieda di più:

- **Email.** Per impostazione predefinita [Elenca le email](/it/docs/api-reference/emails/list/) restituisce le email degli ultimi 14 giorni. Per cercare più indietro, passa `date_from` (e facoltativamente `date_to`) come data, ad esempio `2026-08-01`. I filtri `created_at` non allargano l’intervallo, quindi usa `date_from`.
- **Eventi.** Per impostazione predefinita [Elenca gli eventi](/it/docs/api-reference/events/list/) restituisce gli eventi degli ultimi due giorni. Qualsiasi filtro `created_at`, ad esempio `created_at.after=2026-09-01`, sostituisce questo intervallo. L’elenco si ferma inoltre all’offset 2500: una pagina che inizia oltre il 2500° evento restituisce `422` con il codice `events_offset_too_large`. Per raggiungere eventi più vecchi, restringi i risultati con i filtri `type` o `created_at`.

## Recupera tutte le pagine

Continua il ciclo finché l’API non indica che non c’è una pagina successiva. Questi esempi raccolgono tutti i contatti di una lista:

**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"])
```

## Risultati coerenti

Le pagine vengono calcolate al momento della richiesta. Se vengono creati o eliminati oggetti mentre scorri un elenco ordinato a partire dal più recente, gli oggetti possono spostarsi da una pagina all’altra, quindi potresti vederne uno due volte o perderne uno. Per un’esportazione stabile di un elenco che continua a crescere, ordina a partire dal meno recente con `order=created_at&direction=asc` (o `sort=created_at&order=asc` per contatti e soppressioni) e salta gli ID che hai già visto.

## Vedi anche

  - [Filtri e ordinamento](/it/docs/api-reference/filtering/): Restringi e ordina i risultati degli elenchi.
  - [Limiti di frequenza](/it/docs/api-reference/rate-limits/): Mantieni ragionevoli le letture in blocco.

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