Paginazione

Ogni endpoint di lista paginata nelle Bird API usa lo stesso contratto basato su cursore: gli stessi parametri di richiesta, la stessa struttura di risposta, la stessa semantica dei cursori. Imparalo una volta su GET /v1/email/messages e si applica ovunque.

Un piccolo numero di collezioni limitate (ad esempio, piani di fatturazione) restituisce un semplice array {"data": [...]} senza campi di paginazione. Gli altri endpoint implementano il contratto di paginazione completo.

Parametri di richiesta

Parametro	Tipo	Descrizione
limit	integer	Numero massimo di elementi per pagina. Tra 1 e 100; il valore predefinito è 25.
starting_after	string	Cursore dal campo next_cursor di una risposta precedente. Restituisce gli elementi immediatamente dopo quella posizione.
ending_before	string	Cursore dal campo prev_cursor di una risposta precedente. Restituisce gli elementi immediatamente prima di quella posizione.
include_total	boolean	Quando true, la risposta include un contatore total. Il valore predefinito è false. Disponibile solo sugli endpoint di gestione. Gli endpoint ad alto volume (messaggi, eventi, soppressioni) non lo accettano.

I cursori sono opachi: non sono ID di risorse e il loro formato può cambiare in qualsiasi momento. Ricevili nelle risposte e passali indietro senza modifiche. Un cursore malformato o scaduto restituisce una 422 con codice E01012 InvalidCursor. Riavvia la paginazione senza cursore.

La maggior parte degli endpoint di lista accetta anche parametri sort e order specifici per la risorsa; il riferimento del singolo endpoint documenta i campi di ordinamento ammessi. Cambiare l'ordinamento invalida i cursori dell'ordinamento precedente.

Struttura della risposta

Esempio di codice

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

Campo	Descrizione
data	La pagina di elementi.
next_cursor	Passalo come starting_after per recuperare la pagina successiva. null quando non esiste una pagina successiva: è il segnale per fermarsi.
prev_cursor	Passalo come ending_before per tornare indietro. null quando non esiste una pagina precedente (sempre null alla prima pagina).
refresh_cursor	Un'ancora di aggiornamento: salvalo, poi passalo come ending_before in seguito per recuperare gli elementi apparsi dopo questa risposta. Non-null ogni volta che data non è vuoto.
total	Totale degli elementi che corrispondono ai filtri della richiesta su tutte le pagine. Presente solo quando è stato passato include_total=true; altrimenti null/assente.

next_cursor e prev_cursor sono indipendenti: ciascuno è null esattamente quando la propria direzione non ha ulteriori pagine. Controlla next_cursor per decidere se recuperare ancora.

Scorrere i risultati

La prima richiesta non porta alcun cursore. Ogni richiesta successiva passa il next_cursor della risposta precedente come starting_after, e ci si ferma quando questo torna null.

Ogni Bird SDK espone gli endpoint di lista in due modalità: iterazione lazy che recupera le pagine in modo trasparente man mano che consumi gli elementi, e un accessor a pagina singola per il controllo manuale del cursore.

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"

Limiti di frequenza

Gli endpoint di lista usano la policy di limitazione delle richieste api_list dell'organizzazione, salvo che l'operazione indichi una policy di prodotto. Questa capacità è separata dal recupero di risorse, dalle scritture e dagli invii. L'iterazione lazy consuma un'unità di policy per ogni richiesta di pagina; usa la dimensione di pagina più grande supportata dall'endpoint per ridurre il numero di richieste.

Correlati

Messaggi email: un endpoint di lista paginata rappresentativo
Concetti SDK: iterazione e accessor a pagina singola negli SDK
Limitazione delle richieste: policy, header e gestione dei 429

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Ottieni un brief di implementazione