設定多租戶平台的入站電子郵件解析 Webhook

設定多租戶平台的入站電子郵件解析 Webhook，確保安全、隔離的子租戶通訊，並嚴格執行速率限制。

入站電子郵件處理的架構概觀

入站電子郵件解析將原始 SMTP 串流轉換為結構化 Webhook 負載，適用於多租戶通訊中樞。當子租戶收件者回覆訊息時，MX 記錄會將 SMTP 工作階段導向邊緣擷取伺服器。解析管線會擷取標頭、多部分 MIME 本文以及原始附件，將其標準化為 JSON 物件。在將這些事件向下游路由之前，平台會驗證網域驗證記錄，例如 SPF、DKIM 等，以確保郵件的真實性。

設定 DNS 記錄與 MX 路由

安全地路由入站郵件需要為每個受管理的傳送網域進行精確的 DNS 設定。子租戶必須佈建指向平台擷取端點的 MX 記錄，以及用於網域擁有權證明的標準 CNAME 驗證器。當您上線網域時，系統會觸發自動化驗證常式，以在啟用即時流量擷取之前驗證 DNS 傳播。所有連入連線均強制執行 TLS 加密，拒絕純文字 SMTP 工作階段。此過程確保了郵件傳輸的機密性與完整性。

Webhook 負載設計與安全性驗證

Webhook 傳遞可靠性取決於決定性的負載結構與強固的端點驗證機制。每個外寄 Webhook 在 HTTP 標頭中都帶有 HMAC-SHA256 簽章，該簽章使用接收子租戶特有的密鑰計算得出。您的擷取伺服器必須在處理 JSON 本文之前驗證此簽章，以防止偽造請求攻擊和未授權的資料注入。負載結構描述包含已解析的欄位，例如寄件者、收件者、主旨和純文字/HTML內文，以及任何附件的元數據。此簽章機制是防止未經授權存取的關鍵安全層。

管理速率限制與背壓

如果缺少速率限制與背壓機制，高容量的入站活動可能會使訂閱者 Webhook 端點不勝負荷。平台會強制執行每個租戶的擷取上限，以保護下游伺服器資源免受意外流量洪流的影響。當流量激增超過正常閾值時，系統會在持續性緩衝區中將傳入的解析排隊，並套用受控的背壓來平滑消耗速率。管理員可以透過營運主控台監控即時產能指標，並調整速率限制參數。此機制對於維持服務穩定性至關重要，並可透過預付錢包餘額進行管理，確保服務持續可用。

營運疑難排解與所需資源

診斷 Webhook 傳遞失敗需要進行結構化記錄檢查，以及對端點可用性進行精確驗證。營運商使用開發人員主控台來重新執行失敗的 Webhook 事件、檢查回應代碼，並檢閱原始負載的格式錯誤。若要深化您的營運設定並維持跨租戶邊界的一致性，請檢閱下列基本說明文件指南。這包括監控 DLR（傳遞狀態報告）的更新，以及配置 OTP（一次性密碼）以進行額外的安全驗證。此外，平台支援配置「安靜時間」，以避免在非工作時間觸發不必要的通知，並確保「走廊」流量的穩定性。

相關閱讀: 電子郵件試行週：正式收件人上線前的驗證檢查 · API 試行週：正式流量的金鑰與 Webhook 設定 · 從試點到生產的 API 速率限制.

開始使用 IOSOR

將 MX 指向解析主機，並為每個租戶建立帶有獨立 shared secret 的入站 webhook URL。在回傳 HTTP 2xx 之前，務必先將 payload 持久化到儲存中。利用 message-id 進行重播，確保 webhook 重試機制不會意外地觸發第二張工單。此過程證明了一封入站信已成功到達該租戶在帳本上的佇列，並為後續處理做好了準備。

IOSOR 要點

丟棄 payload 並回傳 HTTP 200 相當於靜默失敗，應避免。請務必先將數據寫入持久儲存，然後再發送確認響應，切勿反之。正確的操作流程是：先持久化數據，然後發送 2xx 響應；如果發生 5xx 錯誤，則觸發 webhook 重試機制。切勿在解析器仍在緩衝數據時就發送 200 確認，也不要讓多個租戶共用同一個 webhook 密鑰，這會嚴重損害安全性與隔離性。