邮件
发送单封邮件或一批邮件,设置定时发送,并跟踪它从已接受到已送达的全过程。
一封邮件就是一次 POST /emails 请求,或通过 SMTP 中继 发出的一条消息。BillionSend 会检查它、存储它,并立即返回一个 id。发送在后台进行,所以返回 200 只表示邮件已被接受,并不表示已送达。
发送邮件
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 封邮件组成的数组。默认情况下,只要有一封无效,整批都会失败。加上请求头 x-batch-validation: permissive 即可接受其中有效的邮件:data 列出它们的 id,errors 按位置列出其余的邮件。
定时、修改与取消
加上 scheduled_at 可以晚些发送,最多提前 30 天。它接受带时区偏移的 ISO 8601 时间,也接受 in 2 hours 这样的相对时间。邮件处于定时状态时,可以用 PATCH /emails/{id} 修改发送时间,用 POST /emails/{id}/cancel 取消。
跟踪邮件
GET /emails/{id} 返回邮件本身、最新结果 last_event,以及来自 送达率洞察 的 score。在控制台中,邮件 页面列出所有邮件,并按顺序显示它的事件。邮件正文和历史记录保存 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 中继适用同样的规则。