Paginierung

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:

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

Abonnenten auflisten akzeptiert außerdem per_page als Alias für limit.

Antwort

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

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:

Page und per_page

Vorlagen auflisten, Automatisierungen auflisten und Durchläufe auflisten verwenden per_page statt limit und geben Seitenzahlen statt Seiten-URLs zurück:

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

Aggregierte Berichte auflisten und Forensische Berichte auflisten geben die Gesamtzahl zurück, damit Sie wissen, wann Sie aufhören können:

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

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

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