API 基础
BillionSend API 的基础 URL、API 密钥权限、错误列表、速率限制、幂等键和分页说明。
API 参考 中的接口页面由 API 的路由定义生成。OpenAPI 3.1 规范 与之同源,只是合成一个 JSON 文件。
BillionSend API 兼容 Resend API:路径、请求结构和错误格式都相同。可以从 BillionSend 的 SDK 调用,也可以直接发 HTTP 请求。
基础 URL
https://api.billionsend.com
认证
每个请求都要带上控制台 API 密钥 页面中的一个 API 密钥:
Authorization: Bearer bs_...
缺少密钥或密钥格式错误时返回 401 missing_api_key,密钥不正确时返回 401 invalid_api_key。
密钥有权限级别:
- 完全访问 可以使用所有接口。
- 仅发送 只能发送。
/emails之外的所有接口都返回403 restricted_api_key,GET /emails、GET /emails/{id}、GET /emails/metrics、DELETE /emails/{id}和所有/emails/receiving接口也一样,因为它们会返回已存储的内容。
密钥还可以限定在 某一个域名 或 某一个 收件箱。限定在某个域名的密钥只在该域名内工作:只能从它发送,只能读取它的邮件,在 /domains 下只能看到并修改它,对属于整个团队的所有内容(Webhook、抑制列表、模板、联系人属性、/usage、/deliverability、验证、POST /domains)都返回 403 restricted_api_key,参见 API 密钥。你用 API 创建的密钥,权限永远不会比创建它的密钥更宽。
一个团队可以有 25 个有效密钥。哪些操作需要由所有者或管理员创建的密钥,列在 团队角色 中。
错误
每个错误都是这种结构:
{ "statusCode": 422, "name": "validation_error", "message": "..." }
| 状态码与名称 | 含义 |
|---|---|
400 invalid_parameter |
请求体不是有效的 JSON。 |
401 missing_api_key / invalid_api_key |
没有密钥,或密钥不正确。 |
403 restricted_api_key |
密钥的权限或范围不允许这样做。 |
403 forbidden |
你的角色或密钥不允许这个操作。 |
403 plan_limit_reached |
达到了套餐的某项上限。参见 套餐与限额。 |
403 sending_paused |
因退信率或投诉率过高,发送已暂停。 |
404 not_found |
接口或你请求的对象不存在。 |
409 invalid_idempotent_request |
该幂等键曾用于不同的载荷。 |
415 |
请求体不是 application/json。 |
422 validation_error |
请求无效。message 中会说明原因。 |
422 all_recipients_suppressed |
所有收件人都被抑制或已退订。参见 抑制列表。 |
429 rate_limit_exceeded |
请求过多。 |
429 daily_quota_exceeded / monthly_quota_exceeded |
套餐的发送额度已用完。参见 套餐与限额。 |
503 service_unavailable |
统计存储没有响应。发送不受影响。 |
每个 429 都带有 retry-after 头,值是需要等待的秒数。
每个响应(无论是否出错)都带有 x-request-id 头,即该请求的 id,它与控制台 日志 页面上该请求的 id 相同。向我们询问某个请求时,请附上它。
如果收件人的域名永远收不到邮件,例如 x@example.com、x@foo.test 或 x@gmail.con,会被拒绝并返回 422 validation_error。在这样的地址上新建联系人也一样。要在不给任何人发邮件的情况下测试,请发送到 success@simulator.amazonses.com。
收信、收件箱 和 Agent 安全 各自有额外的错误,在这些页面中列出。
速率限制
每个 API 密钥每分钟最多可发出 600 个请求,一个团队的所有密钥合计 3,000 个。超出限制时,你会收到 429 rate_limit_exceeded 和 retry-after 头。同一个 IP 地址每分钟超过 20 次认证失败,也会以同样方式被拒绝。
幂等性
POST /emails 和 POST /emails/batch 接受长度为 1 到 256 个字符的 Idempotency-Key 头。收件箱的回复、转发和草稿发送,以及对收到邮件的回复和转发,也一样。用相同的键和相同的载荷重试,会得到原来的响应,而不是第二封邮件。相同的键搭配不同的载荷会返回 409。
分页
列表接口接受 limit(1 到 100,默认 20)以及游标 after 和 before,两者都是上一页中的某个条目 id。响应中有 has_more。列表默认最新的在前:
after取一页的最后一个 id,返回更早的条目。before取第一个 id,返回更新的条目。
要追上新增的内容,把你保存的最新 id 作为 before 传入。
少数列表采用其他顺序,它们的参考页面中会说明:收件箱会话(最近活动的在前)、会话中的邮件(最早的在前),以及订阅主题和标签(最早的在前,一次返回全部)。不匹配任何条目的游标会返回 422 validation_error(在 /inboxes 下为 404)。
值得了解的规则
- 附件 只接受内联 base64 的
content。远程pathURL 会返回422。每封邮件的附件合计最多 10 MiB,整封邮件必须小于 40 MB。程序和脚本(.exe、.js、.bat等,包括 ZIP 内的)一律被拒绝。对新团队,一些有风险的类型(例如压缩包、网页和启用宏的 Office 文件)会被接受,但在发送前要等待审核。 - 联系人 属于团队。没有受众的概念:受众相关接口是 分群 的别名。
- 退订 属于发信域名。参见 退订。
- 收件人:
to、cc和bcc合计最多 50 个地址,每个都必须是单个邮箱。如果to中的所有地址都被抑制,发送会返回422 all_recipients_suppressed。 - 邮件头 采用白名单:任何
X-*名称(X-SES-*和X-BillionSend-*除外)、会话串联与优先级头,以及List-Unsubscribe这一对。其他任何邮件头都返回422。 - 主题行 最长 998 个字符。
- 额外接口:
GET /usage(套餐、限额与用量)、DELETE /emails/{id},以及GET /emails/metrics(数据分析)。 - 批量联系人:
POST /contacts/batch一次请求最多创建 1,000 位联系人,POST /contacts/batch/remove一次请求最多删除 1,000 位联系人。在联系人列表上加include=properties,topics会附上每位联系人的属性和订阅主题。 - 批量抑制 每次请求最多接受 1,000 个地址。
- 额外的状态:群发可以是
canceled。 - 收信和收件箱 处于 Beta 阶段,对新邮件提供长轮询和实时事件流。参见 收信 和 收件箱。
- 不支持的 设置会以
422拒绝,而不是被悄悄忽略。
带签名的下载链接
收到的邮件带有原始邮件及其附件的下载链接。它们是普通的 GET URL,不需要 API 密钥,有效期一小时,过期后返回 403。需要时再向 API 请求一个新链接。参见 收信。