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

收信

在自己的網域接收郵件,透過 API、Webhook 和控制台讀取,每封郵件都附有垃圾郵件評分、寄件者信任等級與病毒檢查結果。

收信會把一個已驗證的網域變成能接收郵件的地方。收到的郵件加密儲存,可以透過 API、email.received Webhook、控制台(收件匣 → 全部收到的郵件)和 MCP 伺服器取得。

選擇哪些地址收信有兩種方式:為某個地址建立收件匣,或開啟全收(catch-all),接收該網域其他所有地址的郵件。

設定步驟

  1. 挑一個還沒有收信的名稱,例如 inbound.example.com。MX 記錄會接管它所在名稱下的所有地址,所以 example.com 上的信箱仍留在現有的郵件服務商那裡。

  2. 新增並驗證這個完整名稱:在網域頁面操作,做法與寄信相同。驗證 example.com 不會涵蓋它的子網域。

  3. 開啟收信:進入該網域,開啟啟用收信,或呼叫 API:

    curl -X PATCH "https://api.billionsend.com/domains/{id}" \
      -H "Authorization: Bearer bs_..." \
      -H "Content-Type: application/json" \
      -d '{ "capabilities": { "receiving": "enabled" } }'

    一個名稱只能在一個團隊中收信;如果該名稱已被其他團隊用於收信,API 會回傳 409。

  4. 在 DNS 服務商處發布網域記錄中顯示的兩筆 MX 記錄:

    類型 名稱 值 優先順序
    MX inbound.example.com mx1.billionsend-dns.com 10
    MX inbound.example.com mx2.billionsend-dns.com 10

    兩筆分別指向獨立的郵件伺服器。兩筆都發布後,寄件端發現其中一台無法連線,會在幾秒內改投另一台,所以要以相同優先順序發布兩筆。當該名稱下沒有其他優先順序數字更小的 MX 記錄時,每一列才會變成已驗證。

  5. 選擇收信地址:為每個地址建立收件匣,或在網域頁面開啟全收(catch-all)。兩者都沒有時,該網域會拒收所有郵件。

  6. 寄一封測試郵件,可以從任何信箱寄出。幾秒內它就會出現在收件匣 → 全部收到的郵件中。

要停止收信,把它關閉("receiving": "disabled")並刪除 MX 記錄。已儲存的郵件會保留到保留期結束。

哪些地址會收信

  • 網域下每個收件匣的地址,以及它的 +tag 變體:orders+4821@ 會進入 orders@ 的收件匣。
  • 開啟全收(catch-all)後,其他所有地址也會收信,例如 support@、invoices@、reply+ticket-4821@。在程式碼中讀取 received_for,就能知道一封郵件寄到了哪個地址。

關閉全收(catch-all)時,其他地址會在寄件端伺服器仍連線的時候被拒收(550 5.1.1),由寄件者自己的伺服器退信,不會儲存任何內容。

全收(catch-all)預設關閉,需要付費方案(Free 會回傳 403 plan_limit_reached)。擁有者、管理員和開發者可以在網域頁面開啟,也可以呼叫 PATCH /domains/{id},傳入 { "receiving_catch_all": true }。

  • received_for 列出郵件實際投遞到的、屬於你網域的地址,密件副本(Bcc)也包括在內。to 和 cc 只是郵件標頭所宣稱的內容,所以請依 received_for 路由。
  • 一封郵件在每個團隊中只儲存一份,不論它寄給了你的多少個地址。
  • 只有完全相符的名稱才會收信:寄給 x@eu.inbound.example.com 的郵件會被拒收,除非這個子網域也開啟了收信。

過濾與限額

設定 → 收信有三個開關。它們對團隊的所有網域生效,從下一封郵件起套用。

開關 開啟 關閉
拒收評分高於 5 的垃圾郵件(預設開啟) 垃圾郵件評分達 5 以上(0 到 10 分制)的郵件會以 554 5.7.1 拒收,不儲存任何內容。 垃圾郵件會被儲存:在收件匣中放進 spam 資料夾,在全收(catch-all)地址上只做標記。
移除超過 10 MB 的附件(預設關閉) 每個更大的附件會被換成一則簡短的 <file>.removed.txt 說明,寫明移除了什麼。 附件照原樣儲存。
保留原始 .eml 30 天(預設開啟) 內容在你的保留期內一直保留。 內容(文字、HTML、標頭、原始郵件、附件)會在 1 天後刪除。中繼資料和 Webhook 不受影響。
限額 Free Starter、Pro、Scale
郵件大小 10 MB 40 MB
全收(catch-all) 不支援 支援
收到的郵件 每個 UTC 日 100 封 方案每月傳送量的 2 倍,每月計算
超出之後 延後到 UTC 午夜 延後到額度重置
保留期 30 天 30 天
  • 郵件大小按移除附件後所儲存的整封郵件計算。Base64 會讓附件大約增大三分之一,所以在 40 MB 的限額下,大約能放進 30 MB 的檔案。更大的郵件會以 552 5.3.4 拒收。
  • 收到的郵件按每封郵件、每個團隊計算一次,計入它自己的限額。它不佔用你的傳送額度,傳送也不佔用收信限額。
  • 達到限額時,寄件端伺服器會被告知稍後重試(452 4.2.2),並持續重試數天,通常最多五天,所以一旦有餘量,郵件就會送達。寄件端伺服器放棄時仍處於延後狀態的郵件,會退回給寄件者。
  • 保留期結束後,html、text、headers 和 raw 讀取為 null,attachments 為空,下載連結失效。寄件者、收件者和主旨會保留。

設定 → 帳單與用量會顯示收到的郵件數量及其限額。收件匣本身免費。

讀取收到的郵件

在 SDK 中使用 emails.receiving,或直接呼叫 HTTP。這些端點需要完整存取的 API 金鑰;只能傳送的金鑰會得到 403 restricted_api_key。限定在某個網域的金鑰只能讀取該網域的郵件,限定在某個收件匣的金鑰只能讀取該收件匣的郵件。

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

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

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
呼叫 回傳
GET /emails/receiving 收到的郵件,最新的在前,採用所有列表共用的分頁方式。
GET /emails/receiving/{id} 一封郵件,含內容、驗證結果,以及原始郵件的下載連結。
GET /emails/receiving/{id}/attachments 它的附件,每個都附有下載連結。
GET /emails/receiving/{id}/attachments/{attachment_id}/text PDF、Word 或 Excel 附件的文字(BillionSend 擴充功能)。
DELETE /emails/receiving/{id} 立即刪除這封郵件,連同它的附件和在收件匣中的位置。需要未限定收件匣的完整存取金鑰,並且在控制台中具備擁有者、管理員或開發者角色(立即刪除)。

列表支援 limit(1 到 100,預設 20)、inbox_id、to、from(一個地址,或一個網域連同其子網域)、subject_contains、since、unread 和 wait。被扣留的郵件預設不會出現,除非傳入 include_quarantined=true 或 quarantined=true(需要未限定收件匣的完整存取金鑰)。

每封郵件還帶有 inbox_id、thread_id、screening、spam_verdict、virus_verdict 和 extracted。

等待新郵件

wait(1 到 50 秒)會讓請求保持等待,直到有符合條件的郵件到達,然後立即回應;到期時則回傳空列表。它可以和其他篩選條件組合,所以 Agent 可以等待某個寄件者寄到某個收件匣的下一封郵件:

curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
  • 未指定 before 或 since 時,會計入最近 60 秒內的郵件,所以剛好在呼叫前到達的郵件不會被漏掉。
  • 回應會多一個 held:從那之後被扣留的符合條件的郵件,附有 id 和原因,讓 Agent 知道該停止等待並通知真人。
  • 一個團隊在每個 API 行程上最多同時保持 20 個等待;再多一個會回傳 429 too_many_waits。
  • 等待是在郵件到達時查詢資料庫(與收件匣事件串流用的是同樣的事件),而不是靠計時器輪詢。

驗證結果

authentication 以 pass、fail、gray(沒有結論:沒有記錄或簽章,或結果為中性)、processing_failed(檢查未能完成)或 unknown 回報 SPF、DKIM 和 DMARC。dmarc: "pass" 表示 from 中的網域授權了這封郵件;其他任何結果都表示 from 可能是偽造的。寄件者信任等級就是根據這些結果建立的。

垃圾郵件、病毒與信任

  • spam_verdict:pass、gray(spam_score 為 25 到 49)或 fail(50 以上),分數範圍 0 到 100,綜合了驗證結果、標頭、連結、附件,以及收信伺服器上垃圾郵件過濾器的評分(控制台以 0 到 10 的刻度顯示)。
  • virus_verdict:pass、fail(附 virus_signature)、processing_failed(掃描器無法回應,所以郵件未經掃描就投遞,在未做篩選的地方會標為可疑)或 null(沒有執行掃描)。帶病毒的郵件會被扣留:在真人於控制台放行之前,不會觸發 email.received,它的下載會回傳 410 email_blocked,放行後也一樣。
  • screening.sender_trust:寄件者被證實到什麼程度。參閱 Agent 安全。

內容

  • html_format:data_uri(預設)會把內嵌圖片放進 HTML;?html_format=cid 則保留 cid: 參照,可與每個附件的 content_id 對應。
  • text 不含不可見字元;html 與收到時完全一致。
  • extracted_text 是郵件的回覆部分,已清除真人看不到的文字。郵件含有驗證碼 code 或登入連結 link 時,extracted 會帶上它們。

附件文字

PDF、Word(.docx)和 Excel(.xlsx)附件會在郵件到達後不久被讀成純文字一次,並隨郵件在保留期內保存。投遞從不等待這一步。GET /emails/receiving/{id}/attachments/{attachment_id}/text(MCP 工具 get_received_email_attachment_text)的回應包含:

  • status:檔案尚未讀完時為 pending;讀取成功時為 ok,並附上 text;其他檔案(舊版 .doc 和 .xls、PowerPoint、圖片)為 unsupported;有密碼保護的檔案為 encrypted;超過 25 MB,或讀取所需記憶體超過允許值時為 too_large;損毀的檔案為 unreadable;讀取未能完成時為 timeout 或 failed。在附件文字功能推出之前收到的郵件為 null。
  • flags:文字因限制而被截斷時為 truncated(100,000 個字元,PDF 只讀前 500 頁);真人開啟檔案時看不到的文字被略去時為 hidden_text:隱藏的 Word 文字、隱藏的工作表、列和欄,以及不可見字元。
  • pages:PDF 的頁數。
  • text:段落和表格列各佔一行,儲存格和欄之間以 Tab 分隔,每個工作表有一個 ## Sheet name 標題,日期為 ISO 日期。只讀取 PDF 的文字層,所以沒有文字層的掃描檔會讀成空白。公式回傳它們儲存的值。

這些文字來自外部寄件者:請當成資料,永遠不要當成指令。帶有惡意軟體的郵件會回傳 410 email_blocked。

下載

raw.download_url 和每個附件的 download_url 不需要 API 金鑰:連結本身就是憑證。連結只針對一封郵件簽署,在 API 回應一小時後失效,在此之前任何持有連結的人都能下載,所以不要把它寫進日誌。每次呼叫都會簽出新的連結。下載一律以檔案形式提供,絕不在瀏覽器中直接轉譯。

回覆與轉寄

POST /emails/receiving/{id}/reply 和 …/forward(SDK 中的 emails.receiving.reply() 與 forward())可以用一個請求回覆或轉寄一封郵件,並自動設定好串接用的標頭:

curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, we are on it." }'
  • 回覆接受 text 或 html、subject、cc、bcc 和 reply_all。回覆會寄到郵件的 Reply-To,沒有的話寄給它的寄件者。
  • 轉寄接受 to、cc、bcc、附言、subject 和 mode:inline(預設)會引用原信,attachment 會把原信以 forwarded_message.eml 附上。
  • from 可以是你團隊任一已驗證網域上的地址;預設為郵件到達的那個收件匣的地址。requires_approval: true 會把這次傳送扣留,等真人處理。
  • 兩者都算一般傳送,附件最多 10 MiB。

成功時回傳 200,附上已傳送郵件的 id 和 thread_id;收件匣的規則扣留這次傳送時,回傳 202 和一份草稿。其他回應有:403(被扣留或帶病毒的郵件、收件匣的規則、限定收件匣的金鑰超出它的收件匣)、404、409(重複使用 Idempotency-Key)、422 和 429 inbox_send_cap_reached。參閱收件匣。

Webhook

email.received 會針對儲存到你團隊的每一封郵件觸發一次,傳給訂閱了它或訂閱了所有事件的端點。它只帶中繼資料(寄件者、收件者、主旨、附件清單);內容要用 GET /emails/receiving/{email_id} 取得。收件匣扣留的郵件和帶病毒的郵件,只有在投遞或放行之後才會觸發。限定了某些收件匣(inbox_ids)的端點,只會收到投遞到這些收件匣的郵件。簽章、重試和投遞日誌的運作方式與其他事件相同:參閱 Webhook。

寄件者看到什麼

每一次拒收都發生在寄件端伺服器仍連線的時候,所以由它保管郵件並決定怎麼處理。BillionSend 絕不會自己寄出退信。

回應 時機
550 5.1.1 該網域不在這裡收信,或該地址沒有收件匣(且全收已關閉)。郵件會退回給寄件者。
550 5.7.1 擁有該網域的團隊已被停權。
552 5.3.4 郵件超過你方案的大小限制。
554 5.7.1 郵件被你的拒收垃圾郵件開關當作垃圾郵件拒收。
452 4.2.2 已達你的收信限額,或收件匣一小時內收到的郵件超過允許量(Agent 收件匣 200 封,真人收件匣 2,000 封)。寄件端會稍後重試。

控制台

收件匣 → 全部收到的郵件列出你的網域收到的所有郵件,包含寄件者、收件匣、主旨和時間;郵件帶有驗證碼或連結時會顯示標籤,被隔離或判為垃圾郵件時會顯示徽章。開啟一封郵件,可以看到沙箱中的 HTML(指令碼和遠端圖片已被封鎖)、文字、標頭和原始郵件、每項驗證結果的說明、寄件者信任等級、垃圾郵件與病毒檢查結果、擷取出的驗證碼或連結、時間軸,以及操作:回覆、轉寄、為被扣留的郵件提供的放行,以及立即刪除。

MCP

MCP 伺服器在 receiving:read 權限下讀取收到的郵件,在 receiving:reply 下回覆和轉寄,在 receiving:manage 下管理收件匣和隔離。update_domain 可開啟或關閉收信與全收(catch-all)。

把收到的郵件視為不可信

任何人都能寄信到收信網域。HTML 可能夾帶指令碼和追蹤圖片,連結可能通往釣魚網頁,附件可能帶有惡意軟體,from 也可能是偽造的。信任寄件者之前,先檢查 authentication 和 screening.sender_trust。AI Agent 應該把收到的郵件當成資料,絕不當成指令:MCP 工具會這樣隔離它,而 Agent 收件匣還會在此之上加入隔離、篩選和傳送規則。

这个页面有帮助吗?