# Pagination

> Parcourez les endpoints de liste de l’API Emailit avec page et limit, lisez next_page_url, gérez les formats per_page et offset, ainsi que les fenêtres temporelles des listes d’e-mails et d’événements.

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 :

| Paramètre | Description |
| --- | --- |
| `page` | La page à renvoyer, à partir de `1`. Par défaut : `1`. |
| `limit` | Nombre d’objets par page, de `1` à `100`. Les valeurs hors de cette plage renvoient une erreur de validation `400`. |

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

| `limit` par défaut | Endpoints |
| --- | --- |
| 10 | Domaines, clés API, listes de contacts, contacts, campagnes, formulaires, adresses bloquées, webhooks, listes de vérification d’e-mails |
| 25 | E-mails, abonnés |
| 50 | Résultats des listes de vérification d’e-mails |
| 100 | Événements |

[Lister les abonnés](/fr/docs/api-reference/audiences/subscribers/list/) accepte aussi `per_page` comme alias de `limit`.

### Réponse

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

| Champ | Description |
| --- | --- |
| `data` | Les objets de cette page, du plus récent au plus ancien, sauf si vous les [triez](/fr/docs/api-reference/filtering/). |
| `next_page_url` | Chemin de la page suivante, ou `null` sur la dernière page. |
| `previous_page_url` | Chemin de la page précédente, ou `null` sur la première page. |

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

| Champ | Endpoints | Contenu |
| --- | --- | --- |
| `total_records` | Contacts, listes de contacts, campagnes, formulaires | Le nombre d’objets correspondants, toutes pages confondues. |
| `usage` | Webhooks | `used` et `limit` : endpoints de webhook utilisés et autorisés par votre forfait, ainsi que `filters_allowed`. |
| `usage` | Abonnés | `used` et `limit` : abonnés de la liste et nombre maximal autorisé, ainsi que le `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Domaines | Le nombre de domaines d’envoi autorisés par votre forfait (`null` signifie aucune limite), le nombre de domaines que vous avez et le nom du forfait. |

## Page et per_page

[Lister les modèles](/fr/docs/api-reference/templates/list/), [Lister les automatisations](/fr/docs/api-reference/automations/list/) et [Lister les exécutions](/fr/docs/api-reference/automations/runs/) utilisent `per_page` au lieu de `limit` et renvoient des nombres de pages au lieu d’URL de page :

| Paramètre | Description |
| --- | --- |
| `page` | La page à renvoyer, à partir de `1`. Par défaut : `1`. |
| `per_page` | Nombre d’objets par page, de `1` à `100`. Par défaut : `25`. |

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

| Paramètre | Description |
| --- | --- |
| `limit` | Nombre de lignes à renvoyer. Rapports : `25` par défaut, `100` au maximum. Sources, pays, réseaux et émetteurs de rapports : `50` par défaut, `200` au maximum. |
| `offset` | Nombre de lignes à ignorer. Par défaut : `0`. |

[Lister les rapports agrégés](/fr/docs/api-reference/dmarc/list/) et [Lister les rapports forensiques](/fr/docs/api-reference/dmarc/forensic/) renvoient le nombre total, ce qui vous permet de savoir quand vous arrêter :

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

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

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

  - [Filtrage et tri](/fr/docs/api-reference/filtering/): Affinez et ordonnez les résultats des listes.
  - [Limites de débit](/fr/docs/api-reference/rate-limits/): Gardez des lectures en masse raisonnables.

---
Source: https://emailit.com/fr/docs/api-reference/pagination/