Pagination

Tous les endpoints de liste paginée de Bird API utilisent le même contrat à base de curseurs : les mêmes paramètres de requête, la même enveloppe de réponse, la même sémantique de curseur. Apprenez-le une fois sur GET /v1/email/messages et il s'applique partout.

Un petit nombre de collections bornées (par exemple, les plans de facturation) renvoient un simple tableau {"data": [...]} sans champs de pagination. Les autres endpoints implémentent le contrat de pagination complet.

Paramètres de requête

Paramètre	Type	Description
limit	integer	Nombre maximum d'éléments par page. Entre 1 et 100 ; valeur par défaut 25.
starting_after	string	Curseur issu du champ next_cursor d'une réponse précédente. Renvoie les éléments situés immédiatement après cette position.
ending_before	string	Curseur issu du champ prev_cursor d'une réponse précédente. Renvoie les éléments situés immédiatement avant cette position.
include_total	boolean	Lorsque true, la réponse inclut un compteur total. Valeur par défaut false. Disponible uniquement sur les endpoints de gestion. Les endpoints de données à fort volume (messages, événements, suppressions) ne l'acceptent pas.

Les curseurs sont opaques : ce ne sont pas des identifiants de ressource et leur format peut changer à tout moment. Recevez-les dans les réponses et renvoyez-les tels quels. Un curseur malformé ou expiré renvoie une 422 avec le code E01012 InvalidCursor. Relancez la pagination sans curseur.

La plupart des endpoints de liste acceptent aussi des paramètres sort et order spécifiques à la ressource ; la référence de chaque endpoint documente les champs de tri autorisés. Changer le tri invalide les curseurs issus de l'ordre de tri précédent.

Enveloppe de réponse

Exemple de code

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

Champ	Description
data	La page d'éléments.
next_cursor	Renvoyez-le comme starting_after pour récupérer la page suivante. null lorsqu'il n'y a pas de page suivante, ce qui est le signal d'arrêt.
prev_cursor	Renvoyez-le comme ending_before pour revenir en arrière. null lorsqu'il n'y a pas de page précédente (toujours null sur la première page).
refresh_cursor	Point d'ancrage de rafraîchissement : enregistrez-le, puis renvoyez-le comme ending_before plus tard pour récupérer les éléments apparus depuis cette réponse. Non nul tant que data n'est pas vide.
total	Nombre total d'éléments correspondant aux filtres de la requête sur l'ensemble des pages. Présent uniquement lorsque include_total=true a été passé ; sinon null/absent.

next_cursor et prev_cursor sont indépendants : chacun vaut null exactement lorsque sa propre direction n'a plus de page. Vérifiez next_cursor pour décider s'il faut relancer une requête.

Parcourir les résultats

La première requête ne contient pas de curseur. Chaque requête suivante passe le next_cursor de la réponse précédente comme starting_after, et vous vous arrêtez lorsqu'il revient null.

Chaque Bird SDK expose les endpoints de liste de deux façons : une itération paresseuse qui récupère les pages de manière transparente à mesure que vous consommez les éléments, et un accesseur de page unique pour le contrôle manuel du curseur.

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"

Limites de débit

Les endpoints de liste partagent le groupe de limitation du débit list, distinct des lectures de ressources individuelles et des écritures. Paginer à travers une grande collection ne consomme jamais votre quota d'envoi ou de gestion. L'itération paresseuse émet une requête par page, donc une boucle serrée sur une grande collection épuise le groupe list à raison d'une requête par limit éléments ; utilisez limit=100 pour les lectures en masse.

Ressources associées

Messages e-mail : un endpoint de liste paginée représentatif
Concepts SDK : itération et accesseurs de page unique dans les SDK
Limites de débit : groupes, en-têtes et gestion des 429

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first email

Obtenir un guide d'implémentation