---
title: 範本
description: 可重複使用的 Email 範本，用於群發，可在控制台或透過 API 管理。
seo:
  title: Email 範本
ai:
  exclude: true
---

Email 範本是可重複使用的 Email 內容：包含主旨、HTML，以及可選的純文字部分。為下一次[群發](/docs/zh-hant/concepts/broadcasts)先準備好一份。在控制台的**範本**中，你可以用區塊編輯器建立，也可以自己撰寫 HTML。

在群發編輯器中選擇範本，會把它的內容複製進來作為起點。之後編輯或刪除範本，不會改動你已經建立的群發。

## 合併欄位

範本可以帶入依聯絡人而異的值：

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

- `{{{FIRST_NAME}}}`、`{{{LAST_NAME}}}` 與 `{{{EMAIL}}}` 是內建欄位。其他任何名稱都會讀取同名的[聯絡人屬性](/docs/zh-hant/concepts/contacts)。
- `{{{NAME|fallback}}}` 在聯絡人沒有值時，會使用備用文字。
- `{{{UNSUBSCRIBE_URL}}}` 會變成每位收件者自己的退訂連結。請見[退訂](/docs/zh-hant/concepts/unsubscribes)。

## 區塊編輯器與 HTML

- 用區塊編輯器建立的範本，可以用**改用 HTML 編輯**切換成 HTML。你可以另存一份副本，或直接就地修改。在儲存之前，**返回區塊編輯**可以還原區塊。
- 透過 API 以 `html` 建立的範本會在 HTML 模式開啟，你的 HTML 會完全照原樣保留。是否轉換成區塊由你決定，可以另存副本或就地轉換，轉換時會把以表格排版的版面攤平。
- 在 HTML 模式下，由 HTML 產生的純文字部分會持續跟著你的編輯更新。透過 API 設定的純文字部分，則會照儲存的內容寄出。

## 發布與版本

透過 API，每次儲存都會立即生效：每次 `POST /templates` 與 `PATCH /templates/{id}` 都會發布新版本，所以 `status` 一律是 `published`，而 `POST /templates/{id}/publish` 什麼也不做，直接回應成功。在控制台中，編輯器會保留一份工作副本：你的編輯在選擇**發布**之前都只是草稿，**發布**會發布新版本。**版本記錄**會列出每個已發布的版本，**還原為草稿**則把其中一個版本帶回成工作副本。

## Email 範本 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`。請在群發上設定寄件人與 reply-to，並直接使用合併欄位：聯絡人屬性不需要先宣告。
- 不能在 `POST /emails` 或 `POST /broadcasts` 傳入範本 id。請自己傳送 `html` 或 `text`。群發編輯器的範本選擇器則會把內容複製進來。
