跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

收件箱

把邮件按会话收进来、再从同一个地址回复的邮箱,可以给 AI Agent 用,也可以给人用,支持安全规则、隔离、审批与实时事件流。

收件箱是一个邮箱地址:收到的邮件按会话归档,也从同一个地址发信。可以交给 AI agent,由它通过 API、Webhook 或 MCP 服务读取;也可以交给人,在控制台里阅读。收件箱可以是你的某个收信域名上的地址,也可以是 BillionSend 共享域名上的地址,后者不需要配置 DNS。

SDK 以 inboxes.* 覆盖了收件箱的所有接口,包括安全规则、隔离、审批和实时事件流。

Agent 还是人

每个收件箱都有一个 kind,创建时选定,之后不能更改。这个类型决定各项安全设置的默认值。

设置 Agent 人员
accept_from verified anyone
screening 开 关
extract_codes 开 开
send_policy reply_only open(共享域名上为 reply_only)
require_approval 关 关
private_codes 开 关
send_cap 200(共享域名上为 50) 无(共享域名上为 50)
  • agent 是省略 kind 时的默认值。发件域名无法为其担保的发件人,邮件会在隔离区等待;其他外部发件人的邮件会接受提示词注入筛查;agent 在已有会话里回复,它发起的新对话会变成草稿,等人审批。见 Agent 安全。
  • human 面向在控制台里阅读的人:所有人的邮件都会投递(认证失败的进入 spam 文件夹),不做任何筛查。

带病毒的邮件在所有收件箱里都会被隔离。

创建收件箱

在控制台里打开收件箱,选择创建收件箱。或者调用 API:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'

用 Node.js SDK:

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // 读取 BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});

响应(201)是完整的收件箱对象:id、name、email_address、domain_id、kind、shared、expires_at、unread(含未读邮件的会话数)、drafts、quarantined、pending_approval 等。

字段 规则
email_address 你团队某个已验证且能收信的域名上的地址。会转为小写;@ 前的部分最多 64 个字母、数字和 . _ % + -。之后不能更改。省略它则使用共享域名上的地址。
username 省略 email_address 时,是共享域名上 @ 前的部分;省略它,地址随机生成。若给出你自己某个域名的 domain_id,则是该域名上 @ 前的部分。
domain_id GET /domains 返回的一行:你团队的共享子域名(shared: true),或你的某个已验证域名。
name 1 到 320 个字符;省略时用地址。
from_name 收件箱发出邮件的显示名,最多 78 个字符:只能是普通名称,不含 @、:、<、>、换行、链接或电话号码。
kind agent(默认)或 human。
expires_in 收件箱何时过期,例如 1h、24h 或 7d;省略则永不过期。
safety 任意安全设置。
forwarding true 会在共享域名上添加一个 receiving_address,用来把你在别处保留的邮箱转发进这个收件箱。
响应 何时出现
409 validation_error 已有其他收件箱使用这个地址。系统不会替你另选名称。
403 validation_error 达到了你套餐的收件箱数量上限。
429 rate_limit_exceeded 最近一小时创建的收件箱过多,或共享域名的名称审核已达到今天的上限。retry-after 说明何时重试。
422 validation_error 域名未验证或不收信,username 违反规则或被保留,或者某项设置违反规则。
503 name_review_unavailable 共享域名上的名称暂时无法审核。稍后重试。

其他调用:

  • GET /inboxes 列出收件箱,最新的在前(?kind=agent 或 ?kind=human 可以收窄范围)。
  • GET /inboxes/{id} 读取一个。/inboxes/{id}/… 路径里的每个 {id},既可以填收件箱的 id,也可以填它的邮箱地址。
  • PATCH /inboxes/{id} 修改 name、from_name 或 expires_in。
  • DELETE /inboxes/{id} 删除收件箱及其会话、草稿和标签,并吊销它的 API 密钥。同时也投递到了其他收件箱或全域收信(catch-all)地址的邮件,会留在那里。

地址

你自己的域名

自己域名上的收件箱,要求该域名可以收信:已验证、已启用收信,并且已发布 MX 记录。每封邮件按发件方服务器投递到的地址来分派:

  1. 先看有没有地址完全相同的收件箱;
  2. 没有的话,对于 name+tag@,投到 name@ 的收件箱;
  3. 再没有,如果域名打开了全域收信(catch-all),就进入全部收到的邮件,不属于任何收件箱;关闭全域收信(catch-all)时,该地址被拒收(550 5.1.1)。

从收件箱的地址发出的邮件,在所有入口都遵守这个收件箱的规则:POST /emails、批量接口、SMTP 中继和 MCP。给收件箱用一个你的应用尚未用来发信的地址。

共享域名

共享域名上的收件箱不需要 DNS。每个团队在 BillionSend 的共享域名上有自己的子域名,按团队命名。省略 email_address,或把共享行的 id 作为 domain_id 传入,再用 username 指定地址:

curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'

不带 username 时,地址随机生成。用户名在以下情况会被拒绝(422):属于保留名(postmaster、abuse、admin、security、support、noreply、no-reply、billing、hostmaster、webmaster、mailer-daemon、root),以 fwd- 开头,或者看起来像知名品牌。已被占用的用户名返回 409。

名称审核。 你选的用户名、from_name 和团队的子域名,在发布前都会经过审核,防止冒充品牌、银行、政府或官方角色的名称。被拒绝的名称返回 422。审核暂时无法给出结果时,你会得到 503 name_review_unavailable;新团队的子域名会反复重试直到通过,24 小时后团队改用 team- 加六个随机字符。一个 UTC 日内被拒绝的名称超过 20 个,或审核超过 200 次,之后到 UTC 午夜前一律返回 429。

共享地址遵循它们自己的规则,因为这个域名属于所有团队:

  • 除非 expires_in 另有设置,它们会一直存在到被删除,并计入你套餐的收件箱数量上限。90 天无人使用的会被删除。
  • 在 Free 套餐上,以及名称看起来像知名品牌的地址,只能在自己的会话里回复,回复对象限于发件域名为其担保的发件人,以及你团队成员的登录地址。在付费套餐上,人可以从这些地址发起对话;agent 则要满足 send_policy 为 open 且团队已度过最初几次发送,否则它的新对话会作为草稿等人处理。每封发给陌生人的邮件在发出之前都会做钓鱼检查。被拒绝时返回 403 inbox_send_policy。
  • 每封邮件最多发给 10 个收件人。一个收件箱每天最多向 50 个收件人发送(send_cap 取 1 到 50),你团队所有共享地址合计每个 UTC 日最多触达 1,000 个收件人;超出则返回 429 inbox_send_cap_reached。
  • from 必须与收件箱的地址完全一致,邮件不能带 scheduled_at、reply_to、附件或自定义邮件头(否则 422)。POST /emails/batch、群发和 SMTP 中继一律拒绝共享地址。
  • forward_to 只接受成员的登录地址。

发给共享域名上 postmaster@ 和 abuse@ 的邮件会进入 BillionSend,不会进入任何收件箱。

把邮箱转发进收件箱

forwarding: true 适用于邮件存放在别处的地址,例如 Google Workspace 邮箱。收件箱会得到一个 receiving_address,即你团队共享子域名上的一个随机地址:把邮箱转发到那里,收件箱就能收到邮件,并从自己的地址回复。这时域名只需要验证到可以发信即可。

过期

expires_in 是一个数字加 h 或 d,范围从 1h 到 365d;省略则收件箱永不过期。用新的 expires_in 发起 PATCH 时,从那一刻开始计时,传 null 则移除过期时间。expires_at 显示它何时结束。

到 expires_at 时收件箱停止工作:发给它的邮件被拒收(550 5.1.1),读取返回 404,它的 API 密钥失效。一小时内它会被删除,先触发 inbox.expired Webhook,再触发 inbox.deleted。修改过期时间需要开发者、管理员或所有者角色。

会话

收件箱里的每封邮件都属于一个会话,一个会话同时包含两个方向:收件箱收到的,和它发出的。

  • 回复如何找到所属会话。 收件箱发出的邮件,其 References 头里带有一个会话令牌。回复满足以下任一条件时,会进入同一个会话:带有这个令牌,In-Reply-To 指向收件箱发出的某封邮件,或引用了该会话里更早的一封邮件。主题永远不会把邮件并入会话。
  • 文件夹。 一个会话位于一个文件夹:inbox、archive、spam、sent 或 trash。新邮件会把已归档或已发送的会话移回 inbox。DELETE 把会话移入 trash,30 天后清空。
  • 已读状态。 带 read 的 PATCH 会标记整个会话。被扣留的邮件不会让会话变为未读。在人员收件箱里,打开会话就标记为已读;在 agent 收件箱里,已读状态由你的 agent 掌握。
  • 标签。 每个收件箱最多 100 个,名称 1 到 64 个字符,颜色写成 #RRGGBB。
调用 作用
GET /inboxes/{id}/threads 会话列表,最近有动静的在前。筛选条件:folders、labels、read、include_quarantined。
GET /inboxes/{id}/threads/search 同样的筛选条件,外加 query(支持 "exact phrase" 和 -excluded)、from、to、cc、bcc、has_attachment、start_date、end_date。
GET /inboxes/{id}/threads/{thread_id} 一个会话。
PATCH /inboxes/{id}/threads/{thread_id} 设置 read 或 folder。
POST / PUT / DELETE …/threads/{thread_id}/labels 添加、替换或移除标签。
DELETE /inboxes/{id}/threads/{thread_id} 把会话移入垃圾箱。
GET /inboxes/{id}/threads/{thread_id}/emails 它的邮件,最早的在前。

搜索按整词匹配,不区分大小写,范围包括:主题、发件人(地址和显示名)、收件人、收到邮件的正文(含它引用的更早邮件)、附件名,以及 PDF、Word 和 Excel 附件的文本(在这些文本读取完成之后)。中文、日文和韩文文本会被分词。query 的每个词都必须在同一封邮件里的某处匹配;from、to、cc 和 bcc 接受地址或名称里的词。已发送的邮件按主题、发件人和收件人搜索。

matched_email_id 是该会话里最匹配的一封,highlights 标出它的主题、发件人和收件人里的匹配词(只有正文或附件名匹配时为 {})。新邮件在到达后一两秒内就能被搜索到。搜索暂时不可用时,调用返回 503,带 search_unavailable 和 Retry-After 头;其他调用照常工作。

会话里的一封邮件带有 direction、from、to、cc、bcc、reply_to、subject、message_id、html、text、attachments、read 和 received_at。收到的邮件还有 extracted_text(回复部分,已清除隐藏文字)、screening、spam_verdict 和 virus_verdict。

从收件箱发信

POST /inboxes/{id}/emails(SDK 里是 inboxes.send())一次调用就能从收件箱地址发起一段新对话。

curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "success@simulator.amazonses.com",
    "subject": "Your order 1042",
    "text": "It ships today. The invoice is attached.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'

它接受 to、subject、html 和 / 或 text,以及可选的 cc、bcc、attachments 和 requires_approval。收件箱的规则与回复时一样做出决定,响应也和回复相同:200 带 { "id", "thread_id" },规则扣留这次发送时(收件箱不能发起对话、过了爬坡期的首次收件人、requires_approval: true)返回 202 和草稿。限定到某个收件箱的密钥可以为它自己的收件箱调用它。

附件与 POST /emails 接受的相同:filename 和 base64 编码的 content,内嵌图片可以再带 content_type 和 content_id。远程 path 返回 422。回复、转发、新发送和草稿都支持附件,解码后合计最多 10 MiB(转发还要计入原邮件的文件);可执行程序和伪装类型的文件返回 422,共享域名上的收件箱不支持附件。

回复与转发

curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, your order ships today." }'

回复发往这封邮件的 Reply-To,没有则发往它的发件人。reply_all 会把其他 to 和 cc 地址作为 cc 加上;bcc 永远不会被复制。一次发送最多 50 个收件人。…/forward 必须带 to,可以附一段备注,并引用原邮件及其附件,外加你添加的 attachments(合计最多 10 MiB)。两者都接受 attachments,也接受 requires_approval: true,让人来审批这次发送。agent 收件箱发出的回复带有 Auto-Submitted: auto-replied。

响应 含义
200 已发送:{ "id", "thread_id" }。
202 扣留,等人处理:返回草稿,带 status: "pending_approval" 和它的 approval_reasons。
403 inbox_send_policy 收件箱的规则直接拒绝这次发送。
403 email_quarantined 这封邮件被隔离,或带有病毒。
403 restricted_api_key 限定到某个收件箱的密钥访问了另一个收件箱。
429 inbox_send_cap_reached 收件箱的每日上限已用完;retry-after 计时到 UTC 午夜。

要回复任何收到的邮件,不论它在不在收件箱里,请用 POST /emails/receiving/{id}/reply。

草稿与审批

草稿可以是独立的(用于一段新对话),也可以是带 thread_id 和 reply_to_email_id 的回复。它的 status:

status 含义
draft 正在撰写;在调用 …/send 或到达它的 send_at 之前不会被发送。
pending_approval 一次发送被扣留,等待人处理。approval_reasons 说明原因。7 天后过期。
sent 已发送;email_id 指向那封邮件。
rejected 有人驳回了它。
expired 7 天内无人批准。
调用 作用
POST /inboxes/{id}/drafts 创建草稿:to、cc、bcc、subject、text、html、attachments,回复还要加 thread_id 和 reply_to_email_id。回复草稿不会复制收件人,所以发送前要设置 to。
GET /inboxes/{id}/drafts 未发送的草稿,最近更新的在前。
GET / PATCH / DELETE /inboxes/{id}/drafts/{draft_id} 读取、修改(设置 text 或 html 会替换整个正文,attachments 会替换整个列表)或删除草稿;已发送后返回 409。
POST /inboxes/{id}/drafts/{draft_id}/send 发送它。成功返回 200,带已发送邮件的 id 和 thread_id;被扣留时返回 202;没有收件人时返回 422。
POST /inboxes/{id}/drafts/{draft_id}/reject 驳回草稿(仅限审批人)。

草稿把 attachments 与正文分开加密保存,读回时按位置给出 id、filename、content_type 和 size,不返回内容。草稿发送时,附件随邮件一起发出;被扣留的发送会把它携带的文件留在草稿里。草稿一旦发送、被驳回、过期或被删除,它的文件就没有了,30 天的内容清理会删掉残留的部分。

定时发送。 在 POST 或 PATCH 上设置 send_at(BillionSend 扩展),草稿会在之后发送,发送身份是设置它的人(编辑定时草稿的内容会让编辑者成为发送身份):值可以是带时区偏移的 ISO 8601 时间,也可以是相对时间,如 "in 2 hours",最多提前 30 天;已过去的时间会在一分钟内发送,null 取消。到那时草稿需要有收件人,而且只有 draft 状态可以设置定时:等待审批的草稿返回 409。到了 send_at,这次发送会像当时发出的一样走完所有规则和限额。发送成功后草稿变为 sent;被收件箱的规则扣留则变为 pending_approval;被拒绝(设置定时的密钥已被吊销、收件箱已不存在、达到了某个限额)则仍是 draft,send_at 变回 null,拒绝原因的名称写在 send_error 里,并触发 inbox.draft.send_failed Webhook,它带有 error: { name, message }。再次设置定时会清除 send_error。带 send_at 时,为同一封邮件再创建第二个回复草稿会返回 409,而不是返回已有草稿。

谁来审批。 控制台里的人,或者团队里未限定到某个收件箱的完全访问 API 密钥,可以通过发送来批准:这次发送会跳过扣留 agent 邮件的那些规则。agent 不能批准:限定到某个收件箱的密钥,或者发送待审草稿的 MCP 客户端,会得到 403 approval_required。在控制台里,任何成员都可以在收件箱的待审核标签页里批准、编辑或丢弃草稿,有内容在等待时,所有者每天会收到一封邮件。

发送被扣留的原因:

原因 被扣留是因为
approval_required 请求要求由人处理(requires_approval: true)。
require_approval 这个收件箱的每次发送都要审批。
send_policy 某个收件人不被收件箱的发送策略允许。
ramp 对一个新建的收件箱来说,今天的新收件人太多。
private_code 邮件里含有收件箱收到的验证码或登录链接。
loop_guard:<reason> 它在回复一封自动邮件(外出自动回复、邮件列表、退信)。
loop_burst 一小时内对同一个地址的自动回复过多。
reply_to_redirect 这封邮件的 Reply-To 指向另一个组织。

安全设置

GET /inboxes/{id}/safety 读取收件箱的规则,PATCH 修改其中任何一项:

curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
设置 作用
accept_from 谁的邮件可以进入收件箱:anyone;verified,即发件域名为 From 地址担保的发件人(外加所有者、允许列表和已知会话);或 allowlist,仅限所有者、允许列表和已知会话。其余的进入隔离区。
allowlist 最多 500 项:name@domain,或 *@domain,表示一个域名及其子域名。
owner_addresses 除团队成员的登录地址之外,最多再有 50 个被视为这个收件箱所有者的地址。在共享域名上被忽略。
screening 对外部发件人的邮件评估提示词注入和钓鱼风险(agent 收件箱)。
extract_codes 从邮件里提取验证码和登录链接。
send_policy reply_only;allowlist,在此基础上允许与所有者和允许列表发起新对话(共享域名上不可用);或 open,任何人,前提是团队已度过最初几次发送。
require_approval 这个收件箱的每次发送都要等人处理。
private_codes 收件箱收到的验证码或登录链接,只能发给所有者和允许列表里的人。
send_cap 收件箱每个 UTC 日无需人工即可发送的收件人数:1 到 100,000,或 null 表示不设上限(共享域名上为 1 到 50)。
forward_to 最多 5 个地址,会收到除垃圾邮件之外每封已投递邮件的副本:团队成员的登录地址或所有者地址。无法立即发出的副本会持续重试,直到发出、被永久拒绝或过了两天;它不会被发送两次。

违反规则的设置返回 422 并附原因。限定到某个收件箱的密钥不能修改这些设置(403 restricted_api_key),agent 密钥也不能。MCP 客户端可以读取它们,但不能修改。只有所有者、管理员或开发者可以修改,方式是在控制台里,或使用完全访问的 API 密钥。每一项的具体作用见 Agent 安全。

隔离

收件箱的规则不放行的邮件会被隔离:保留、可列出、可放行,既不会被丢弃,也不会退回给发件人。在放行之前,它不会触发 email.received 或 inbox.email.received,agent 也永远看不到它。

GET /inboxes/{id}/quarantine 列出被扣留的邮件,含 id、from、subject、quarantine_reason、sender_trust、injection_score、phishing_score 和 virus_signature,不含内容。POST /inboxes/{id}/quarantine/{email_id}/release 投递其中一封,加上 { "trust_sender": true } 还会把它的发件人加入允许列表。两者都需要未限定到某个收件箱的完全访问密钥。人在收件箱的待审核标签页里放行,带 receiving:manage 的 MCP 客户端用 release_email。谁可以放行哪一种扣留,见 Agent 安全。

验证码

GET /inboxes/{id}/codes/latest 返回收件箱最新收到的验证码或登录链接,所以 agent 不需要去读 HTML:

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
  • kind 是 otp(验证码在 code 里)或 link(地址在 url 里,附带 link_domain_matches_sender)。
  • from 把范围收窄到某个发件人;wait(0 到 50 秒)等待新的一封到达;max_age(60 到 86,400 秒,默认 600)跳过更旧的验证码;since 跳过在该时间或更早收到的邮件,所以把你已经用过的那个验证码的 received_at 传进去,就能等下一个。
  • status 是 found、none、ambiguous(两个验证码可能性相当,所以一个都不返回)或 timeout。响应始终是 200。
  • 验证码永远不会来自被隔离的邮件、认证失败的发件人,或 extract_codes 关闭的收件箱。每次读取都会记录在收件箱的活动里。

事件流

GET /inboxes/events 是一个服务器推送事件(SSE)流,包含你的收件箱里发生的一切,事件提交的瞬间就会推出。事件沿用 Webhook 的事件名(inbox.email.received、inbox.thread.created、inbox.draft.created、email.received 和其他 inbox.* 事件),并带有 Webhook 载荷里的 data。GET /inboxes/{id}/events 只推送一个收件箱的事件,该收件箱被删除或过期时结束。

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
  • 密钥用 Bearer 头发送,与所有请求一样。浏览器的 EventSource 无法设置它:改用 fetch 读取响应体,或任何支持自定义头的 SSE 客户端。
  • types 把流收窄到某些事件,用逗号分隔;/inboxes/{id}/events 仍会发送 inbox.deleted 和 inbox.expired,也就是让它结束的事件。与 Webhook 一样,每个事件都只含元数据:没有正文、验证码或链接。邮件要通过收信接口读取。
  • 断线续传。 每个事件都有一个 id。客户端用 Last-Event-ID(或 ?last_event_id=)重新连接时,会先按顺序收到错过的事件,再接上实时事件。事件保留 24 小时;用更早的 id 重连,会先收到一个 stream.gap 事件,意思是事件可能有缺失,应当重新读取列表。
  • 没有 Last-Event-ID 时,流从头开始,不回放。服务器大约每 10 分钟会关闭一次流,API 重启时也会关闭:用你看到的最后一个 id 重连。retry: 1000 请客户端等待一秒。每 15 秒一行注释,防止代理关闭空闲的流。
  • 团队级密钥可以打开 /inboxes/events。限定到某个域名或某个收件箱的密钥,可以为它能访问的收件箱打开 /inboxes/{id}/events。只能发信的密钥不能打开流。
  • agent(限定到某个收件箱的密钥,或 MCP 连接)永远收不到 inbox.email.quarantined,不论实时还是回放,因为它从不读取被扣留的邮件;在 types 里指定它会返回 403 restricted_api_key。
  • 当密钥被吊销、创建密钥的人离开团队,或它的收件箱被删除或过期后,流会在几秒内关闭。
  • 每个密钥在每个 API 进程上最多同时持有 5 个流,每个团队 25 个;再多一个返回带 retry-after 的 429 too_many_streams。对大多数 agent 来说,整个团队用一个流就够了。

/emails/receiving 和 codes/latest 上的 wait 由同样的事件唤醒,所以没有邮件到达时,等待不产生任何开销。

限定到收件箱的 API 密钥

给每个 agent 一把只能访问它自己收件箱的密钥。见 API 密钥。

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
  • 它需要 permission: "full_access",并且不能同时带 domain_id。一个收件箱最多有 5 把有效密钥,不计入团队 25 把的上限。
  • 这把密钥可以读取它的收件箱(会话、邮件、草稿、标签、验证码、事件流,以及限定到该收件箱的 /emails/receiving),回复、转发,撰写并发送草稿,从它的收件箱发送新邮件,并且只能使用该收件箱的地址发信(用别的 from 返回 403 restricted_api_key;通过 SMTP 则是 550 5.7.1)。
  • 其他一切都返回 403 restricted_api_key:它不能修改安全设置,不能列出或放行隔离邮件,不能批准草稿,不能创建密钥,也不能访问另一个收件箱。
  • 收件箱过期时它就停止工作,删除收件箱会吊销它。

在控制台里,所有者、管理员和开发者在创建密钥时,可以在限定到某个收件箱下选择收件箱。

Webhook

收件箱事件(inbox.created、inbox.thread.created、inbox.email.received、inbox.email.sent、inbox.email.quarantined、inbox.expired、inbox.draft.* 系列事件等)只发送给明确订阅了它们的端点,不会发送给订阅所有事件的端点。端点可以用 inbox_ids 限定到某些收件箱。收件箱的邮件在投递之后,仍会触发 email.received。载荷见 Webhook。

活动

在收件箱里做的每件事都有记录:发送和规则的决定、拒绝、草稿、审批、放行、验证码读取、安全设置变更、删除和密钥。收件箱的活动标签页列出这些记录,并注明是谁操作的:一个人、一把 API 密钥或一个已连接的应用。决定只保留原因代码,不保留内容、验证码或地址。

限额

限额 数值
收件箱数量 Free 3 个,Starter 25 个,Pro 和 Scale 不限。
每小时创建的收件箱 Free 10 个,Starter 60 个,Pro 和 Scale 600 个。
每个收件箱的邮件量 agent 收件箱每个滚动小时接收 200 封,人员收件箱 2,000 封。超出后,发件方收到 452 4.2.2 并稍后重试。
发送 每个 UTC 日 send_cap 个收件人。新收件箱逐步触达新收件人:发送的第一天 10 个,之后 20、40、80、160,依此类推,直到上限。
每次发送的收件人 50(to、cc 和 bcc 合计);共享地址发出的为 10。
每次发送的附件 解码后合计 10 MiB;共享地址不能带附件。
共享域名 你团队所有共享地址合计每个 UTC 日 1,000 个收件人;90 天未使用的共享收件箱会被删除。
标签 每个收件箱 100 个。
安全列表 500 项允许列表,50 个所有者地址,5 个 forward_to 地址。
限定到收件箱的密钥 每个收件箱 5 把有效密钥。
筛查 每个收件箱每天 200 封;超出后,需要筛查的邮件会被隔离。
等待 每个请求 50 秒;每个团队在每个 API 进程上同时 20 个等待。
事件流 每个 API 密钥 5 个、每个团队 25 个,在每个 API 进程上同时存在;事件回放 24 小时。
草稿与垃圾箱 待审草稿 7 天后过期;垃圾箱里的会话 30 天后删除。
保留期 收件箱邮件遵循收信的保留期:30 天。

收件箱本身不收费:收到的邮件按每封计一次,计入你的收信限额,从不计入你的发信额度,与收信里一样。

控制台

侧栏里的收件箱在全部、Agent 和人员标签页下列出你的收件箱,并显示需要关注的事项:待批准的草稿、未读会话和被隔离的邮件。固定的全部收到的邮件一行会打开你的域名收到的所有邮件。收件箱页面有四个标签页:会话(就地阅读、回复和批准草稿)、待审核(草稿和隔离)、安全与规则和活动。

任何成员都可以处理收件箱的会话、批准草稿和放行隔离邮件。所有者、管理员和开发者还可以创建、修改和删除收件箱,修改安全规则,创建限定到收件箱的密钥,删除收到的邮件,以及打开全域收信(catch-all)。见团队角色。

MCP

MCP 客户端通过三项权限使用收件箱:receiving:read(读取邮件、等待邮件、读取验证码、列出收件箱、会话、标签和草稿、搜索会话、读取安全规则)、receiving:reply(回复、转发、从收件箱发信、撰写、发送和删除草稿、整理会话和标签)以及 receiving:manage(创建、修改和删除收件箱,列出并放行隔离邮件)。MCP 客户端看到的邮件始终是 agent 视角:没有被扣留的邮件,邮件文本被标注为不可信。它从不批准草稿,create_inbox 只接受 accept_from,不接受其他安全设置;它从不修改收件箱的安全规则。

API 说明

  • 创建收件箱或草稿时,返回完整的对象。
  • email_address 是可选的:省略时,收件箱会在共享域名上得到一个随机的永久地址。
  • kind 默认为 agent,所以不带它创建的收件箱会得到 agent 的各项保护。
  • 没有托管的 agent:GET /inboxes/{id}/agent 返回空的 instructions、tone 和 actions,PATCH /inboxes/{id}/agent 返回 422。
  • 不支持:回复、转发和草稿发送上的自定义 headers,以及 path(远程 URL)附件。除非值为空,否则各返回 422。
  • 被收件箱的规则扣留的回复、转发或草稿发送,返回带草稿的 202,而不是带邮件的 200:把结果当作已发送之前,先检查 object 是否为 inbox_draft。
  • 收件箱的错误:403 inbox_send_policy、429 inbox_send_cap_reached、403 approval_required、403 email_quarantined 和 503 name_review_unavailable(见错误)。
  • inbox.* Webhook 事件需要主动订阅;inbox.thread.assigned 和 inbox.thread.unassigned 不会发送。

这个页面有帮助吗?