# Paginierung

> Listen-Endpunkte der Emailit-API mit page und limit seitenweise abrufen, next_page_url auswerten, die Formate per_page und offset nutzen und die Zeitfenster für E-Mails und Events beachten.

Listen-Endpunkte geben Ergebnisse seitenweise zurück. Die meisten verwenden Seitennummern mit `page` und `limit`, Vorlagen und Automatisierungen verwenden `page` und `per_page`, und DMARC-Endpunkte verwenden `limit` und `offset`. Diese Seite erklärt jedes Format, die Zeitfenster der E-Mail- und Event-Listen und wie Sie alle Seiten in einer Schleife abrufen.

## Page und Limit

Die meisten Listen-Endpunkte akzeptieren zwei Query-Parameter:

| Parameter | Beschreibung |
| --- | --- |
| `page` | Die abzurufende Seite, beginnend bei `1`. Standardwert `1`. |
| `limit` | Objekte pro Seite, von `1` bis `100`. Werte außerhalb dieses Bereichs geben einen Validierungsfehler mit `400` zurück. |

Die Standardgröße einer Seite hängt vom Endpunkt ab:

| Standardwert für `limit` | Endpunkte |
| --- | --- |
| 10 | Domains, API-Schlüssel, Kontaktlisten, Kontakte, Kampagnen, Formulare, Sperrungen, Webhooks, E-Mail-Verifizierungslisten |
| 25 | E-Mails, Abonnenten |
| 50 | Ergebnisse von E-Mail-Verifizierungslisten |
| 100 | Events |

[Abonnenten auflisten](/de/docs/api-reference/audiences/subscribers/list/) akzeptiert außerdem `per_page` als Alias für `limit`.

### Antwort

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

| Feld | Beschreibung |
| --- | --- |
| `data` | Die Objekte auf dieser Seite, die neuesten zuerst, sofern Sie sie nicht [sortieren](/de/docs/api-reference/filtering/). |
| `next_page_url` | Pfad der nächsten Seite oder `null` auf der letzten Seite. |
| `previous_page_url` | Pfad der vorherigen Seite oder `null` auf der ersten Seite. |

Die Seiten-URLs sind Pfade, keine vollständigen URLs, und bei den meisten Endpunkten enthalten sie nur `page` und `limit`, nicht Ihre Filter. Um die nächste Seite abzurufen, wiederholen Sie Ihre eigene Anfrage mit einem um eins erhöhten `page`. Hören Sie auf, wenn `next_page_url` den Wert `null` hat.

Einige Listen enthalten neben `data` weitere Felder:

| Feld | Endpunkte | Enthält |
| --- | --- | --- |
| `total_records` | Kontakte, Kontaktlisten, Kampagnen, Formulare | Die Anzahl der passenden Objekte über alle Seiten. |
| `usage` | Webhooks | `used` und `limit` für die Webhook-Endpunkte Ihres Tarifs sowie `filters_allowed`. |
| `usage` | Abonnenten | `used` und `limit` für die Abonnenten der Kontaktliste sowie den `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Domains | Wie viele Versanddomains Ihr Tarif erlaubt (`null` bedeutet kein Limit), wie viele Sie haben und der Name des Tarifs. |

## Page und per_page

[Vorlagen auflisten](/de/docs/api-reference/templates/list/), [Automatisierungen auflisten](/de/docs/api-reference/automations/list/) und [Durchläufe auflisten](/de/docs/api-reference/automations/runs/) verwenden `per_page` statt `limit` und geben Seitenzahlen statt Seiten-URLs zurück:

| Parameter | Beschreibung |
| --- | --- |
| `page` | Die abzurufende Seite, beginnend bei `1`. Standardwert `1`. |
| `per_page` | Objekte pro Seite, von `1` bis `100`. Standardwert `25`. |

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

Rufen Sie weitere Seiten ab, solange `current_page` kleiner als `total_pages` ist.

## Limit und Offset

Die DMARC-Endpunkte überspringen eine Anzahl von Zeilen, statt Seiten zu zählen:

| Parameter | Beschreibung |
| --- | --- |
| `limit` | Anzahl der zurückzugebenden Zeilen. Berichte: Standardwert `25`, höchstens `100`. Quellen, Länder, Netzwerke und Berichtersteller: Standardwert `50`, höchstens `200`. |
| `offset` | Anzahl der zu überspringenden Zeilen. Standardwert `0`. |

[Aggregierte Berichte auflisten](/de/docs/api-reference/dmarc/list/) und [Forensische Berichte auflisten](/de/docs/api-reference/dmarc/forensic/) geben die Gesamtzahl zurück, damit Sie wissen, wann Sie aufhören können:

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

Die Endpunkte für Aufschlüsselungen geben `meta` nur mit `limit` und `offset` zurück. Hören Sie auf, wenn eine Seite weniger Zeilen als `limit` enthält.

## Zeitfenster

Zwei Listen berücksichtigen nur aktuelle Daten, sofern Sie nicht mehr anfordern:

- **E-Mails.** [E-Mails auflisten](/de/docs/api-reference/emails/list/) gibt standardmäßig E-Mails der letzten 14 Tage zurück. Übergeben Sie `date_from` (und optional `date_to`) als Datum wie `2026-08-01`, um weiter zurück zu suchen. Filter auf `created_at` erweitern das Fenster nicht. Verwenden Sie deshalb `date_from`.
- **Events.** [Events auflisten](/de/docs/api-reference/events/list/) gibt standardmäßig Events der letzten zwei Tage zurück. Jeder Filter auf `created_at`, etwa `created_at.after=2026-09-01`, ersetzt dieses Fenster. Die Liste endet außerdem bei einem Offset von 2.500: Eine Seite, die nach dem 2.500. Event beginnt, gibt `422` mit dem Code `events_offset_too_large` zurück. Grenzen Sie die Ergebnisse mit den Filtern `type` oder `created_at` ein, um ältere Events zu erreichen.

## Alle Seiten abrufen

Rufen Sie Seiten in einer Schleife ab, bis die API meldet, dass es keine nächste Seite gibt. Diese Beispiele sammeln alle Kontakte einer Kontaktliste:

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

## Konsistente Ergebnisse

Seiten werden zum Zeitpunkt der Anfrage berechnet. Werden Objekte erstellt oder gelöscht, während Sie durch eine Liste blättern, die die neuesten Objekte zuerst zeigt, können sich Objekte zwischen den Seiten verschieben. Sie sehen dann womöglich eines doppelt oder verpassen eines. Für einen stabilen Export einer wachsenden Liste sortieren Sie mit `order=created_at&direction=asc` die ältesten zuerst (bei Kontakten und Sperrungen mit `sort=created_at&order=asc`) und überspringen IDs, die Sie bereits gesehen haben.

## Siehe auch

  - [Filtern und Sortieren](/de/docs/api-reference/filtering/): Listenergebnisse eingrenzen und ordnen.
  - [Rate Limits](/de/docs/api-reference/rate-limits/): Massenhafte Lesezugriffe in vernünftigem Rahmen halten.

---
Quelle: https://emailit.com/de/docs/api-reference/pagination/