Paginazione

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:

La dimensione di pagina predefinita dipende dall’endpoint:

Elenca gli iscritti accetta anche per_page come alias di limit.

Risposta

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

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:

Page e per_page

Elenca i template, Elenca le automazioni ed Elenca le esecuzioni usano per_page invece di limit e restituiscono il numero di pagine invece degli URL delle pagine:

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

Elenca i report aggregati ed Elenca i report forensi restituiscono il conteggio totale, così sai quando fermarti:

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

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

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