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 utilisent la politique de limitation du débit api_list à l'échelle de l'organisation, sauf si l'opération désigne une politique produit. Cette capacité est distincte de la récupération de ressources, des écritures et des envois. L'itération paresseuse consomme une unité de politique par requête de page ; utilisez la taille de page maximale acceptée par l'endpoint pour réduire le nombre de requêtes.

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
Limitation du débit : politiques, 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