---
title: 邮件模板
description: 可重复使用的邮件内容，用于群发，可在控制台或通过 API 管理。
seo:
  title: 邮件模板
ai:
  exclude: true
---

模板是可重复使用的邮件内容：主题行、HTML，以及可选的纯文本部分。为下一次 [群发](/docs/zh-hans/concepts/broadcasts) 准备好一份邮件模板。在控制台的 **模板** 中，可以用区块编辑器搭建，也可以自己编写 HTML。

在群发编辑器里选择模板时，会把它的内容复制进来作为起点。之后修改或删除模板，不会影响你已经创建的群发。

## 邮件模板的合并字段

模板可以包含按联系人填充的值：

```html
<p>Hi {{{FIRST_NAME|there}}},</p>
```

- `{{{FIRST_NAME}}}`、`{{{LAST_NAME}}}` 和 `{{{EMAIL}}}` 是内置字段。其他任何名称都会读取同名的 [联系人属性](/docs/zh-hans/concepts/contacts)。
- `{{{NAME|fallback}}}` 在联系人没有该值时使用备用文本。
- `{{{UNSUBSCRIBE_URL}}}` 会变成每位收件人自己的退订链接。参见 [退订](/docs/zh-hans/concepts/unsubscribes)。

## 区块编辑器与 HTML

- 用区块编辑器创建的模板，可以通过 **改用 HTML 编辑** 切换为 HTML。你可以得到一份副本，也可以就地修改。保存之前，**返回区块** 可以恢复为区块。
- 通过 API 用 `html` 创建的模板会以 HTML 模式打开，你的 HTML 会完全按原样保留。是否转换为区块由你决定，可以转成副本或就地转换，转换会把基于表格的布局展平。
- 在 HTML 模式下，由 HTML 生成的纯文本部分会持续跟随你的修改。通过 API 设置的纯文本部分则按存储的内容发送。

## 发布与版本

通过 API 操作时，每次保存都会立即生效：每个 `POST /templates` 和 `PATCH /templates/{id}` 都会发布一个新版本，所以 `status` 始终是 `published`，`POST /templates/{id}/publish` 什么也不做，但会成功返回。在控制台中，编辑器会保留一份工作副本：你的修改在你点击 **发布** 之前都只是草稿，点击后会发布一个新版本。**版本历史** 列出所有已发布的版本，**恢复为草稿** 会把某个版本恢复为工作副本。

## API

SDK 把模板接口作为 `templates.*` 调用。

```bash
curl -X POST https://api.billionsend.com/templates \
  -H "Authorization: Bearer $BILLIONSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "subject": "Welcome to Acme",
    "html": "<p>Hi {{{FIRST_NAME|there}}}</p>",
    "alias": "welcome"
  }'
```

- `POST /templates` 接受 `name`、`html`，以及可选的 `subject`、`text` 和 `alias`。
- `GET /templates` 列出模板，最新的在前。`GET /templates/{id}` 返回完整内容。
- `PATCH /templates/{id}` 可以修改其中任何字段。空字符串或 `null` 会清除 `subject` 或 `text`。写入 `html` 或 `text` 会把区块编辑器模板变成 HTML 模板。
- `DELETE /templates/{id}` 删除模板。
- `POST /templates/{id}/duplicate` 创建一份名为 `<name> (copy)` 的副本，不带别名。

`alias` 由字母、数字、`.`、`_` 和 `-` 组成，最长 100 个字符，在你的团队内唯一。上面的每个路由都可以用别名代替 id。别名已被占用时返回 `409`。形如 UUID 的别名不被允许。

## 不支持的功能

- 在模板上设置 `from`、`reply_to` 和 `variables` 会返回 `422`。请在群发上设置发件人和回复地址，并直接使用合并字段：联系人属性无需声明。
- 不能用 `POST /emails` 或 `POST /broadcasts` 发送模板 id。请自己发送 `html` 或 `text`。群发编辑器的模板选择器会把内容复制进来。
