---
title: 邮件
description: 发送单封邮件或一批邮件，设置定时发送，并跟踪它从已接受到已送达的全过程。
seo:
  title: 发送邮件 API
ai:
  exclude: true
---

一封邮件就是一次 `POST /emails` 请求，或通过 [SMTP 中继](/docs/zh-hans/smtp) 发出的一条消息。BillionSend 会检查它、存储它，并立即返回一个 `id`。发送在后台进行，所以返回 `200` 只表示邮件已被接受，并不表示已送达。

## 发送邮件

```ts
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` 发起同样的调用：

```bash
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`：必须属于你的团队已 [验证的域名](/docs/zh-hans/concepts/domains)。
- `to`、`cc`、`bcc`、`reply_to`：一个地址或一个地址列表。`to`、`cc` 和 `bcc` 合计最多 50 个收件人。
- `html` 和 `text`：至少需要其中一个。不支持用模板 id 发送。[模板](/docs/zh-hans/concepts/templates) 是可以复制到群发中的内容。
- `tags`、`headers`、`attachments`：规则、附件限制和幂等性参见 [API 基础](/docs/zh-hans/api-reference/basics)。
- `topic_id`：已退出该 [订阅主题](/docs/zh-hans/concepts/topics) 的收件人会被跳过。

这些示例中的地址 `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`，以及来自 [送达率洞察](/docs/zh-hans/concepts/deliverability-insights) 的 `score`。在控制台中，**邮件** 页面列出所有邮件，并按顺序显示它的事件。邮件正文和历史记录保存 30 天。

| 事件 | 含义 |
| --- | --- |
| `email.scheduled` | 已接受，正在等待发送时间。 |
| `email.sent` | 已交付给投递环节。 |
| `email.delivered` | 收件人的服务器已接受。 |
| `email.delivery_delayed` | 投递被延迟，之后会重试。 |
| `email.bounced` | 收件人的服务器拒收。 |
| `email.complained` | 收件人把它标记为垃圾邮件。 |
| `email.failed` | 无法发送。事件中会说明原因。 |
| `email.suppressed` | 未发送，因为所有收件人都被抑制或已退订。 |
| `email.opened`、`email.clicked` | 收件人打开了邮件或点击了链接（需开启 [邮件追踪](/docs/zh-hans/concepts/tracking)）。 |

每个事件也可以通过 [Webhook](/docs/zh-hans/concepts/webhooks) 推送给你。

## 什么会阻止或暂扣发送

出现以下情况时，发送会被拒绝，并返回说明原因的 `4xx` 错误：

- 发信域名未验证（`422`）；
- 所有收件人都被 [抑制](/docs/zh-hans/concepts/suppressions)（`422 all_recipients_suppressed`）；
- 超出了套餐的发送量（`429`）；
- 你的退信率或投诉率已使发送暂停（`403 sending_paused`）。

有些邮件会被接受但暂扣，稍后再发出：超出每日上限的新域名，或等待限额重置的邮件。参见 [发送限制](/docs/zh-hans/concepts/sending-limits)。API 和 SMTP 中继适用同样的规则。
