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

郵件

寄送單封或批次 Email、排程寄送,並追蹤它從已接受到已送達的過程。

一封 Email 就是一次 POST /emails 請求,或透過 SMTP relay 送出的一封郵件。BillionSend 會先檢查、儲存,並立刻回傳 id。實際寄送在背景進行,所以 200 代表 Email 已被接受,不代表已送達。

寄送 Email

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

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

const { data, error } = await bs.emails.send({
  from: "Acme <hello@mail.example.com>",
  to: ["success@simulator.amazonses.com"],
  subject: "Welcome",
  html: "<p>Thanks for signing up.</p>",
});

用 curl 發出相同的呼叫:

curl -X POST https://api.billionsend.com/emails \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": ["success@simulator.amazonses.com"],
    "subject": "Welcome",
    "html": "<p>Thanks for signing up.</p>"
  }'
  • from:必須是團隊已驗證的網域。
  • to、cc、bcc、reply_to:可以是單一位址或一組位址。to、cc 與 bcc 合計最多 50 位收件者。
  • html 與 text:至少需要其中一個。不支援用範本 id 寄信。範本是讓你複製到群發裡的內容。
  • tags、headers、attachments:規則、附件限制與冪等性請見 API 基礎。
  • topic_id:已退訂該訂閱主題的收件者會被略過。

這些範例中的位址 success@simulator.amazonses.com 是模擬器的位址,不會寄給任何人,可以用來測試。

批次寄送

POST /emails/batch 接受最多 100 封 Email 的陣列。預設只要有一封無效,整個批次就會失敗。加上標頭 x-batch-validation: permissive 就會接受其中有效的:data 列出它們的 id,errors 依位置列出其餘的。

排程、修改、取消

加上 scheduled_at 可以稍後寄送,最多可排到 30 天後。它接受帶有時差的 ISO 8601 時間,或 in 2 hours 這類相對時間。Email 在排程期間,可以用 PATCH /emails/{id} 修改時間,用 POST /emails/{id}/cancel 取消。

追蹤 Email

GET /emails/{id} 會回傳 Email,其中有最新結果 last_event,以及來自送達率洞察的 score。在控制台的郵件頁面會列出每封 Email,並依序顯示它的事件。內文與歷史記錄保存 30 天。

事件 意義
email.scheduled 已接受,等待排定的時間。
email.sent 已交付寄送。
email.delivered 收件者的伺服器已接受。
email.delivery_delayed 送達延遲,稍後會重試。
email.bounced 收件者的伺服器拒收。
email.complained 收件者標記為垃圾郵件。
email.failed 無法寄出。事件會說明原因。
email.suppressed 因為所有收件者都已被抑制或退訂,所以沒有寄出。
email.opened、email.clicked 收件者開啟了信件或點擊了連結,前提是已開啟追蹤。

每個事件也可以用 Webhook 傳送給你。

哪些情況會停止或擱置寄送

在以下情況,寄送會被拒絕,並回傳指出原因的 4xx 錯誤:

  • 寄件網域尚未驗證(422);
  • 所有收件者都已被抑制(422 all_recipients_suppressed);
  • 已超過方案的用量(429);
  • 你的退信率或投訴率已讓寄送暫停(403 sending_paused)。

有些信件會被接受但先擱置,稍後再寄出:新網域超過每日上限,或信件在等待限制重置。請見寄送限制。API 與 SMTP relay 套用相同的規則。

这个页面有帮助吗?