分页

Bird API 中每个分页列表端点都使用相同的基于游标的约定：相同的请求参数、相同的响应信封、相同的游标语义。在 GET /v1/email/messages 上学习一次，即可处处适用。

少数有界集合（例如账单方案）返回不带分页字段的普通 {"data": [...]} 数组。其他端点实现完整的分页约定。

请求参数

参数	类型	描述
limit	integer	每页最大条目数。取值范围为 1 到 100；默认值为 25。
starting_after	string	来自上一次响应 next_cursor 字段的游标。返回该位置之后的条目。
ending_before	string	来自上一次响应 prev_cursor 字段的游标。返回该位置之前的条目。
include_total	boolean	为 true 时，响应中包含 total 计数。默认值为 false。仅在管理端点上可用。高流量数据端点（消息、事件、屏蔽列表）不接受此参数。

游标是不透明的：它们不是资源 ID，其格式可能随时更改。在响应中接收游标并原样传回即可。格式错误或过期的游标会返回 422，错误代码为 E01012 InvalidCursor。此时请不带游标重新开始分页。

大多数列表端点还接受特定于资源的 sort 和 order 参数；各端点的参考文档列出了允许的排序字段。更改排序会使基于先前排序顺序的游标失效。

响应信封

代码示例

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

字段	描述
data	当前页的条目。
next_cursor	作为 starting_after 传回以获取下一页。当没有下一页时为 null，这是停止的信号。
prev_cursor	作为 ending_before 传回以向前翻页。当没有上一页时为 null（第一页始终为 null）。
refresh_cursor	刷新锚点：保存它，之后作为 ending_before 传回以获取自本次响应以来新出现的条目。当 data 非空时始终为非 null。
total	所有页中符合请求过滤条件的条目总数。仅在传入 include_total=true 时存在；否则为 null/缺失。

next_cursor 和 prev_cursor 是独立的：各自在其方向没有更多页时恰好为 null。检查 next_cursor 来决定是否继续请求。

遍历结果

第一个请求不带游标。之后的每个请求将上一次响应的 next_cursor 作为 starting_after 传入，当其返回 null 时停止。

每个 Bird SDK 以两种模式公开列表端点：惰性迭代，在你消费条目时透明地逐页获取；单页访问器，用于手动游标控制。

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"

请求速率限制

列表端点使用组织级别的 api_list 请求速率限制策略，除非该操作指定了产品级策略。此容量与资源读取、写入和发送分开计算。惰性迭代每请求一页消耗一个策略单元；请使用端点支持的最大页面大小以减少请求次数。

分页

请求参数

响应信封

遍历结果

请求速率限制

相关内容

相关资源