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

收件匣

專為 AI Agent 或真人準備的郵件地址:郵件按會話串歸檔,並從同一個地址回覆,附有安全規則、隔離與核准流程。

收件匣是一個郵件地址,它把收到的郵件按會話串歸檔,並從同一個地址傳送郵件。可以把它交給 AI Agent,由 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 金鑰。同時也到達另一個收件匣或全收地址的郵件,會留在那邊。

地址

你自己的網域

你自己網域上的收件匣,要求該網域可以收信:已驗證、已開啟收信,且已發布 MX 記錄。每封郵件依寄件端伺服器投遞到的地址來分派:

  1. 先給地址完全相同的收件匣;
  2. 否則,對 name+tag@,給 name@ 的收件匣;
  3. 否則,網域的全收開啟時,進入沒有收件匣的所有收到的郵件;全收關閉時,該地址會被拒收(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 時,地址為隨機產生。username 屬於保留名稱(postmaster、abuse、admin、security、support、noreply、no-reply、billing、hostmaster、webmaster、mailer-daemon、root)、以 fwd- 開頭,或看起來像知名品牌時,會被拒絕(422)。已被佔用的會回傳 409。

名稱審查。 選定的 username、from_name 和團隊的子網域在發布之前都會經過審查,以阻止冒充品牌、銀行、政府或官方職位的名稱。被拒絕的名稱回傳 422。審查暫時無法回應時,你會得到 503 name_review_unavailable;新團隊的子網域會不斷重試直到通過,24 小時後,團隊會使用 team- 加六個隨機字元。一個 UTC 日內被拒絕的名稱超過 20 個,或審查超過 200 次,回應會是 429,直到 UTC 午夜。

共用地址有自己的規則,因為這個網域屬於所有團隊:

  • 除非 expires_in 另有規定,它們會一直存在直到被刪除,並計入你方案的收件匣數量上限。90 天沒有人使用的地址會被刪除。
  • 在 Free 方案上,以及名稱看起來像知名品牌的任何地址,它們只能在自己的會話串內回覆,對象限於網域為其背書的寄件者和你團隊成員的登入地址。在付費方案上,真人可以從它們發起對話;當 Agent 的 send_policy 為 open 且你的團隊已度過最初的傳送階段時,Agent 也可以;否則它的新對話會變成草稿,等真人處理。每封寄給陌生人的郵件在送出之前都會做釣魚檢查。被拒絕時回傳 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,並觸發帶有 error: { name, message } 的 inbox.draft.send_failed Webhook。重新排程會清除 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 是一個 server-sent event 串流,內容是你的收件匣裡發生的所有事,在事情提交的那一刻就會送出。事件使用 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 個;再多一個會回應 429 too_many_streams 並附上 retry-after。對大多數 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 和真人分頁列出你的收件匣,並顯示需要處理的事項:待核准的草稿、未讀的會話串和在隔離區的郵件。置頂的所有收到的郵件一列會開啟你的網域收到的所有郵件。收件匣的頁面有四個分頁:會話串(就地閱讀、回覆和核准草稿)、待審核(草稿與隔離)、安全與規則和活動。

任何成員都可以處理收件匣的會話串、核准草稿和放行隔離。擁有者、管理員和開發者還可以建立、修改和刪除收件匣、更改安全規則、建立限定收件匣的金鑰、刪除收到的郵件,以及開關全收。參閱團隊角色。

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 不會傳送。

这个页面有帮助吗?