Pagination

Les endpoints de liste renvoient les résultats une page à la fois. La plupart utilisent des numéros de page avec page et limit, les modèles et les automatisations utilisent page et per_page, et les endpoints DMARC utilisent limit et offset. Cette page explique chaque format, les fenêtres temporelles des listes d’e-mails et d’événements, et comment parcourir toutes les pages en boucle.

Page et limit

La plupart des endpoints de liste acceptent deux paramètres de requête :

La taille de page par défaut dépend de l’endpoint :

Lister les abonnés accepte aussi per_page comme alias de limit.

Réponse

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

Les URL de page sont des chemins et non des URL complètes, et sur la plupart des endpoints elles ne contiennent que page et limit, pas vos filtres. Pour récupérer la page suivante, répétez votre propre requête en augmentant page de un, et arrêtez-vous lorsque next_page_url vaut null.

Certaines listes ajoutent des champs à côté de data :

Page et per_page

Lister les modèles, Lister les automatisations et Lister les exécutions utilisent per_page au lieu de limit et renvoient des nombres de pages au lieu d’URL de page :

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

Continuez à demander des pages tant que current_page est inférieur à total_pages.

Limit et offset

Les endpoints DMARC sautent un nombre de lignes au lieu de compter les pages :

Lister les rapports agrégés et Lister les rapports forensiques renvoient le nombre total, ce qui vous permet de savoir quand vous arrêter :

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

Les endpoints de ventilation ne renvoient que limit et offset dans meta. Arrêtez-vous lorsqu’une page contient moins de lignes que limit.

Fenêtres temporelles

Deux listes ne portent que sur des données récentes, sauf si vous demandez davantage :

• E-mails. Lister les e-mails renvoie par défaut les e-mails des 14 derniers jours. Transmettez date_from (et éventuellement date_to) sous forme de date, comme 2026-08-01, pour remonter plus loin. Les filtres created_at n’élargissent pas la fenêtre : utilisez donc date_from.
• Événements. Lister les événements renvoie par défaut les événements des deux derniers jours. Tout filtre created_at, comme created_at.after=2026-09-01, remplace cette fenêtre. La liste s’arrête aussi à un offset de 2 500 : une page qui commence au-delà du 2 500e événement renvoie 422 avec le code events_offset_too_large. Affinez les résultats avec les filtres type ou created_at pour atteindre des événements plus anciens.

Récupérer toutes les pages

Bouclez jusqu’à ce que l’API indique qu’il n’y a plus de page suivante. Ces exemples récupèrent tous les contacts d’une liste de contacts :

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

Résultats cohérents

Les pages sont calculées au moment où vous les demandez. Si des objets sont créés ou supprimés pendant que vous parcourez une liste triée du plus récent au plus ancien, des objets peuvent passer d’une page à l’autre : vous risquez d’en voir un deux fois ou d’en manquer un. Pour un export stable d’une liste qui continue de grandir, triez du plus ancien au plus récent avec order=created_at&direction=asc (ou sort=created_at&order=asc pour les contacts et les adresses bloquées), et ignorez les ID déjà vus.

Voir aussi