Paginering

Elk gepagineerd lijstendpoint in de Bird API gebruikt hetzelfde cursorgebaseerde contract: dezelfde requestparameters, dezelfde response-envelope, dezelfde cursorsemantiek. Leer het één keer op GET /v1/email/messages en het geldt overal.

Een klein aantal begrensde collecties (bijvoorbeeld factureringsplannen) retourneert een gewone {"data": [...]}-array zonder pagineringsvelden. Andere endpoints implementeren het volledige pagineringscontract.

Requestparameters

Parameter	Type	Beschrijving
limit	integer	Maximum aantal items per pagina. Tussen 1 en 100; standaard 25.
starting_after	string	Cursor uit het next_cursor-veld van een eerdere response. Retourneert items direct na die positie.
ending_before	string	Cursor uit het prev_cursor-veld van een eerdere response. Retourneert items direct vóór die positie.
include_total	boolean	Bij true bevat de response een total-telling. Standaard false. Alleen beschikbaar op beheerendpoints. Data-endpoints met hoog volume (berichten, events, suppressies) accepteren deze parameter niet.

Cursors zijn opaque: het zijn geen resource-ID's en hun formaat kan op elk moment veranderen. Ontvang ze in responses en geef ze ongewijzigd terug. Een onjuiste of verlopen cursor retourneert een 422 met code E01012 InvalidCursor. Herstart de paginering zonder cursor.

De meeste lijstendpoints accepteren ook resourcespecifieke sort- en order-parameters; de referentie per endpoint documenteert de toegestane sorteervelden. Het wijzigen van de sortering maakt cursors uit de vorige sorteervolgorde ongeldig.

Response-envelope

Codevoorbeeld

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

Veld	Beschrijving
data	De pagina met items.
next_cursor	Geef terug als starting_after om de volgende pagina op te halen. null als er geen volgende pagina bestaat; dat is het signaal om te stoppen.
prev_cursor	Geef terug als ending_before om terug te bladeren. null als er geen vorige pagina bestaat (altijd null op de eerste pagina).
refresh_cursor	Een verversingsanker: sla het op en geef het later terug als ending_before om items op te halen die sinds deze response zijn verschenen. Niet-null wanneer data niet leeg is.
total	Totaal aantal items dat overeenkomt met de filters van het request, over alle pagina's. Alleen aanwezig als include_total=true is meegegeven; anders null/afwezig.

next_cursor en prev_cursor zijn onafhankelijk: elk is null precies wanneer de eigen richting geen verdere pagina heeft. Controleer next_cursor om te beslissen of je opnieuw moet ophalen.

Door resultaten bladeren

Het eerste request bevat geen cursor. Elk volgend request geeft de next_cursor van de vorige response mee als starting_after, en je stopt wanneer die als null terugkomt.

Elke Bird SDK biedt lijstendpoints in twee modi: luie iteratie die transparant pagina's ophaalt terwijl je items verwerkt, en een single-page accessor voor handmatige cursorbesturing.

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"

Limieten voor het aantal verzoeken

Lijst-endpoints gebruiken het organisatiebrede api_list-rate-limitbeleid, tenzij de operatie een productbeleid noemt. Deze capaciteit staat los van het ophalen van resources, schrijfacties en verzendingen. Lazy iteration verbruikt één beleidseenheid per paginaverzoek; gebruik de grootste paginagrootte die het endpoint ondersteunt om het aantal verzoeken te beperken.

Gerelateerd

E-mailberichten: een representatief gepagineerd lijstendpoint
SDK-concepten: iteratie en single-page accessors in de SDK's
Rate limits: beleid, headers en omgaan met 429s

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptShould I use a Bird SDK or call the API directly?Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Ontvang een implementatieoverzicht