郵件
寄送單封或批次 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 套用相同的規則。