---
title: 郵件
description: 寄送單封或批次 Email、排程寄送，並追蹤它從已接受到已送達的過程。
seo:
  title: Email 寄送 API
ai:
  exclude: true
---

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

## 寄送 Email

```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-hant/concepts/domains)。
- `to`、`cc`、`bcc`、`reply_to`：可以是單一位址或一組位址。`to`、`cc` 與 `bcc` 合計最多 50 位收件者。
- `html` 與 `text`：至少需要其中一個。不支援用範本 id 寄信。[範本](/docs/zh-hant/concepts/templates)是讓你複製到群發裡的內容。
- `tags`、`headers`、`attachments`：規則、附件限制與冪等性請見 [API 基礎](/docs/zh-hant/api-reference/basics)。
- `topic_id`：已退訂該[訂閱主題](/docs/zh-hant/concepts/topics)的收件者會被略過。

這些範例中的位址 `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`，以及來自[送達率洞察](/docs/zh-hant/concepts/deliverability-insights)的 `score`。在控制台的**郵件**頁面會列出每封 Email，並依序顯示它的事件。內文與歷史記錄保存 30 天。

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

每個事件也可以用 [Webhook](/docs/zh-hant/concepts/webhooks) 傳送給你。

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

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

- 寄件網域尚未驗證（`422`）；
- 所有收件者都已被[抑制](/docs/zh-hant/concepts/suppressions)（`422 all_recipients_suppressed`）；
- 已超過方案的用量（`429`）；
- 你的退信率或投訴率已讓寄送暫停（`403 sending_paused`）。

有些信件會被接受但先擱置，稍後再寄出：新網域超過每日上限，或信件在等待限制重置。請見[寄送限制](/docs/zh-hant/concepts/sending-limits)。API 與 SMTP relay 套用相同的規則。
