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

邮件

发送单封邮件或一批邮件,设置定时发送,并跟踪它从已接受到已送达的全过程。

一封邮件就是一次 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 中继适用同样的规则。

这个页面有帮助吗?