Paginação

Todo endpoint de listagem paginada na Bird API usa o mesmo contrato baseado em cursor: os mesmos parâmetros de requisição, o mesmo envelope de resposta, a mesma semântica de cursor. Aprenda uma vez em GET /v1/email/messages e aplique em qualquer lugar.

Um pequeno número de coleções limitadas (por exemplo, planos de cobrança) retorna um array {"data": [...]} simples sem campos de paginação. Os demais endpoints implementam o contrato completo de paginação.

Parâmetros de requisição

Parâmetro	Tipo	Descrição
limit	integer	Máximo de itens por página. Entre 1 e 100; o padrão é 25.
starting_after	string	Cursor do campo next_cursor de uma resposta anterior. Retorna itens imediatamente após essa posição.
ending_before	string	Cursor do campo prev_cursor de uma resposta anterior. Retorna itens imediatamente antes dessa posição.
include_total	boolean	Quando true, a resposta inclui uma contagem total. O padrão é false. Disponível apenas em endpoints de gerenciamento. Endpoints de dados de alto volume (mensagens, eventos, supressões) não aceitam esse parâmetro.

Cursores são opacos: não são IDs de recursos, e seu formato pode mudar a qualquer momento. Receba-os nas respostas e envie-os de volta sem alterações. Um cursor malformado ou expirado retorna uma 422 com código E01012 InvalidCursor. Reinicie a paginação sem cursor.

A maioria dos endpoints de listagem também aceita parâmetros sort e order específicos do recurso; a referência de cada endpoint documenta os campos de ordenação permitidos. Alterar a ordenação invalida cursores da ordem anterior.

Envelope de resposta

Exemplo de código

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

Campo	Descrição
data	A página de itens.
next_cursor	Envie de volta como starting_after para buscar a próxima página. null quando não existe próxima página, o que é o sinal para parar.
prev_cursor	Envie de volta como ending_before para voltar uma página. null quando não existe página anterior (sempre null na primeira página).
refresh_cursor	Uma âncora de atualização: salve-a e envie-a de volta como ending_before depois para buscar itens que surgiram desde esta resposta. Não nulo sempre que data não estiver vazio.
total	Total de itens correspondentes aos filtros da requisição em todas as páginas. Presente apenas quando include_total=true foi enviado; caso contrário, null/ausente.

next_cursor e prev_cursor são independentes: cada um é null exatamente quando sua própria direção não tem mais páginas. Verifique next_cursor para decidir se deve buscar novamente.

Navegando pelos resultados

A primeira requisição não leva cursor. Todas as seguintes passam o next_cursor da resposta anterior como starting_after, e você para quando ele voltar null.

Todo Bird SDK expõe endpoints de listagem em dois modos: iteração lazy que busca páginas de forma transparente conforme você consome itens, e um acessor de página única para controle manual de cursor.

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 requisições

Os endpoints de listagem usam a política de limitação de requisições api_list da organização, a menos que a operação especifique uma política de produto. Essa capacidade é separada da recuperação de recursos, gravações e envios. A iteração lazy consome uma unidade de política por requisição de página; use o maior tamanho de página que o endpoint suporta para reduzir o número de requisições.

Relacionados

Mensagens de e-mail: um endpoint de listagem paginada representativo
Conceitos do SDK: iteração e acessores de página única nos SDKs
Limitação de requisições: políticas, cabeçalhos e tratamento de 429s

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Obtenha um resumo de implementação