Paginación

Todos los endpoints de lista paginada en la Bird API usan el mismo contrato basado en cursores: los mismos parámetros de solicitud, la misma estructura de respuesta, la misma semántica de cursores. Apréndelo una vez en GET /v1/email/messages y aplica en todas partes.

Un número reducido de colecciones acotadas (por ejemplo, planes de facturación) devuelven un array {"data": [...]} simple sin campos de paginación. Los demás endpoints implementan el contrato de paginación completo.

Parámetros de solicitud

Parámetro	Tipo	Descripción
limit	integer	Cantidad máxima de elementos por página. Entre 1 y 100; por defecto 25.
starting_after	string	Cursor del campo next_cursor de una respuesta anterior. Devuelve los elementos inmediatamente después de esa posición.
ending_before	string	Cursor del campo prev_cursor de una respuesta anterior. Devuelve los elementos inmediatamente antes de esa posición.
include_total	boolean	Cuando es true, la respuesta incluye un conteo total. Por defecto false. Disponible solo en endpoints de gestión. Los endpoints de datos de alto volumen (mensajes, eventos, supresiones) no lo aceptan.

Los cursores son opacos: no son IDs de recursos y su formato puede cambiar en cualquier momento. Recíbelos en las respuestas y pásalos de vuelta sin modificar. Un cursor malformado o expirado devuelve un 422 con código E01012 InvalidCursor. Reinicia la paginación sin cursor.

La mayoría de los endpoints de lista también aceptan parámetros sort y order específicos del recurso; la referencia de cada endpoint documenta los campos de ordenamiento permitidos. Cambiar el ordenamiento invalida los cursores del orden anterior.

Estructura de respuesta

Ejemplo de código

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

Campo	Descripción
data	La página de elementos.
next_cursor	Pásalo como starting_after para obtener la página siguiente. null cuando no existe página siguiente, lo cual es la señal para detenerse.
prev_cursor	Pásalo como ending_before para retroceder. null cuando no existe página anterior (siempre null en la primera página).
refresh_cursor	Un ancla de actualización: guárdalo y luego pásalo como ending_before más adelante para obtener los elementos que han aparecido desde esta respuesta. No nulo siempre que data no esté vacío.
total	Total de elementos que coinciden con los filtros de la solicitud en todas las páginas. Presente solo cuando se pasó include_total=true; de lo contrario null/ausente.

next_cursor y prev_cursor son independientes: cada uno es null exactamente cuando su propia dirección no tiene más páginas. Comprueba next_cursor para decidir si solicitar otra vez.

Recorrer los resultados

La primera solicitud no lleva cursor. Cada solicitud posterior pasa el next_cursor de la respuesta anterior como starting_after, y te detienes cuando ese valor vuelve como null.

Cada Bird SDK expone los endpoints de lista en dos modos: iteración lazy que obtiene páginas de forma transparente a medida que consumes elementos, y un accesor de página única para control manual de cursores.

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"

Límites de frecuencia

Los endpoints de lista usan la política de limitación de solicitudes api_list de toda la organización, a menos que la operación indique una política de producto. Esta capacidad es independiente de la obtención de recursos, las escrituras y los envíos. La iteración lazy consume una unidad de política por solicitud de página; usa el tamaño de página más grande que admita el endpoint para reducir la cantidad de solicitudes.

Relacionado

Mensajes de email: un endpoint de lista paginada representativo
Conceptos de SDK: iteración y accesores de página única en los SDK
Limitación de solicitudes: políticas, encabezados y manejo de 429s

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoShould I use a Bird SDK or call the API directly?Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first email

Obtener un resumen de implementación