Paginierung

Jeder paginierte Listen-Endpoint in der Bird API verwendet denselben Cursor-basierten Vertrag: dieselben Request-Parameter, dieselbe Response-Hülle, dieselbe Cursor-Semantik. Lernen Sie ihn einmal bei GET /v1/email/messages kennen, und er gilt überall.

Eine kleine Anzahl begrenzter Sammlungen (zum Beispiel Abrechnungspläne) gibt ein einfaches {"data": [...]}-Array ohne Paginierungsfelder zurück. Andere Endpoints implementieren den vollständigen Paginierungsvertrag.

Request-Parameter

Parameter	Typ	Beschreibung
limit	integer	Maximale Einträge pro Seite. Zwischen 1 und 100; Standardwert ist 25.
starting_after	string	Cursor aus dem next_cursor-Feld einer vorherigen Response. Gibt Einträge unmittelbar nach dieser Position zurück.
ending_before	string	Cursor aus dem prev_cursor-Feld einer vorherigen Response. Gibt Einträge unmittelbar vor dieser Position zurück.
include_total	boolean	Bei true enthält die Response einen total-Zähler. Standardwert ist false. Nur auf Management-Endpoints verfügbar. Daten-Endpoints mit hohem Volumen (Nachrichten, Events, Suppressions) akzeptieren diesen Parameter nicht.

Cursor sind opak: Sie sind keine Ressourcen-IDs, und ihr Format kann sich jederzeit ändern. Empfangen Sie sie in Responses und übergeben Sie sie unverändert zurück. Ein fehlerhafter oder abgelaufener Cursor gibt eine 422 mit Code E01012 InvalidCursor zurück. Starten Sie die Paginierung ohne Cursor neu.

Die meisten Listen-Endpoints akzeptieren zusätzlich ressourcenspezifische sort- und order-Parameter; die Endpoint-Referenz dokumentiert die erlaubten Sortierfelder. Eine Änderung der Sortierung macht Cursor aus der vorherigen Sortierreihenfolge ungültig.

Response-Hülle

Codebeispiel

{
  "data": [{ "...": "..." }],
  "next_cursor": "WyIyMDI2LTA2LTEwVDA5OjE0OjAzWiIsICJtc2dfMDFr...",
  "prev_cursor": null,
  "refresh_cursor": "WyIyMDI2LTA2LTEwVDEyOjAwOjAwWiIsICJtc2dfMDFr...",
  "total": 1432
}

Feld	Beschreibung
data	Die Seite mit Einträgen.
next_cursor	Übergeben Sie diesen Wert als starting_after, um die nächste Seite abzurufen. null, wenn keine nächste Seite existiert – das Signal zum Stoppen.
prev_cursor	Übergeben Sie diesen Wert als ending_before, um rückwärts zu blättern. null, wenn keine vorherige Seite existiert (auf der ersten Seite immer null).
refresh_cursor	Ein Aktualisierungsanker: Speichern Sie ihn und übergeben Sie ihn später als ending_before, um Einträge abzurufen, die seit dieser Response hinzugekommen sind. Nicht null, solange data nicht leer ist.
total	Gesamtzahl der Einträge, die den Filtern des Requests über alle Seiten hinweg entsprechen. Nur vorhanden, wenn include_total=true übergeben wurde; andernfalls null/absent.

next_cursor und prev_cursor sind unabhängig: Jeder ist genau dann null, wenn seine Richtung keine weitere Seite hat. Prüfen Sie next_cursor, um zu entscheiden, ob Sie erneut abrufen.

Durch Ergebnisse blättern

Der erste Request enthält keinen Cursor. Jeder folgende übergibt den next_cursor der vorherigen Response als starting_after, und Sie stoppen, wenn dieser als null zurückkommt.

Jedes Bird SDK stellt Listen-Endpoints in zwei Modi bereit: verzögerte Iteration, die Seiten transparent abruft, während Sie Einträge verarbeiten, und einen Einzelseiten-Accessor für manuelle Cursor-Steuerung.

for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}

for message in client.email.list(status="delivered"):
    print(message.id)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusBounced}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

bird email list

curl -X GET "https://{region}.platform.bird.com/v1/email/messages" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Rate Limits

Listen-Endpoints teilen sich die list-Rate-Limit-Gruppe, getrennt von Lesezugriffen auf einzelne Ressourcen und von Schreibzugriffen. Das Durchblättern einer großen Sammlung verbraucht nie Ihr Sende- oder Management-Kontingent. Verzögerte Iteration sendet einen Request pro Seite. Eine enge Schleife über eine große Sammlung beansprucht also die list-Gruppe mit einem Request pro limit Einträgen; verwenden Sie limit=100 für Massenabrufe.

Paginierung

Request-Parameter

Response-Hülle

Durch Ergebnisse blättern

Rate Limits

Verwandte Themen

Verwandte Ressourcen