电子邮件模板 API

电子邮件模板 API 管理应用程序电子邮件预设背后的可重用电子邮件模板——与您在 Control Panel 的电子邮件编辑器中构建的模板相同。每个模板存储每个区域设置的主题、发件人信息和编辑器内容，并通过与其连接的电子邮件预设的代码进行识别。使用该代码通过 Notify（电子邮件有效负载 email_template）或 Customer Journey 发送电子邮件点发送模板。

基本 URL

https://rpc-api.svc-nue.pushwoosh.com

所有端点都通过 HTTPS 提供服务。除非另有说明，请求和响应使用 application/json。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的服务器 API 令牌：

Authorization: Api YOUR_API_TOKEN

约定

字段命名： 请求体和查询/路径参数接受 lowerCamelCase（例如，previewSettings、searchByLabel、includeHtml）——服务器可以解组任何一种大小写。响应总是使用 proto 字段名以 snake_case 格式进行编组（per_page、email_template、sender_info、preview_settings 等）。下面的响应示例和对象参考使用这种大小写。
code： 每个模板响应都携带其连接的电子邮件预设的代码，而不是内部模板 ID。将此相同的代码传递给 Get、Update、Delete 以及上面的消息/旅程 API。
未填充字段： 响应包括所有字段，即使是空值或零值。

错误响应

HTTP 状态	含义
`400 Bad Request`	无效参数 — 缺少或格式错误的必填字段，或前提条件失败（例如，删除一个仍在旅程中使用的模板）。
`401 Unauthorized`	缺少或无效的 `Authorization` 标头。
`403 Forbidden`	应用程序或预设不属于调用者的帐户。
`404 Not Found`	未找到模板、预设或应用程序。
`500 Internal Server Error`	意外的服务器端故障。

端点

方法	路径	描述
`POST`	`/api/email_templates`	创建一个新的电子邮件模板
`GET`	`/api/email_templates`	列出应用程序的电子邮件模板
`GET`	`/api/email_templates/{code}`	获取单个电子邮件模板
`PUT`	`/api/email_templates/{code}`	更新一个电子邮件模板
`DELETE`	`/api/email_templates/{code}`	删除一个电子邮件模板
`POST`	`/api/email_templates:clone`	将电子邮件模板克隆到应用程序中

创建

在应用程序中创建一个新的电子邮件模板——包括其编辑器内容和一个连接的电子邮件预设——并返回生成的模板代码。

POST /api/email_templates

请求体

参数	类型	必填	描述
`application`	string	是	用于创建模板的 Pushwoosh 应用程序代码。
`name`	string	是	模板名称，1–255 个字符。
`content`	object	是	电子邮件内容对象。
`label`	string	否	自由文本标签，最多 255 个字符。
`categories`	array of strings	否	用于标记模板的类别名称。
`previewSettings`	object	否	任意编辑器预览设置，按原样存储和返回。
`system`	boolean	否	将模板标记为系统模板——一个内部功能，例如同步块片段。系统模板在 `List` 中是隐藏的（见下文注释），但仍可通过代码访问。默认为 `false`。

请求示例

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

响应

返回 { "email_template": { ... } } — 创建的电子邮件模板对象，但不包含 content（此端点不会将其回显）。如果您需要读回内容，请使用返回的 code 调用 Get。

列表

列出应用程序的电子邮件模板——仅元数据，无内容——支持分页、排序以及按名称、标签或类别筛选。

GET /api/email_templates

查询参数

参数	类型	必填	描述
`application`	string	是	要列出模板的应用程序代码。
`orderBy`	string	否	`NAME` (默认), `CREATED`, 或 `UPDATED`。
`orderDirection`	string	否	`ASC` (默认) 或 `DESC`。
`page`	integer	否	从零开始的页面索引。
`perPage`	integer	否	页面大小。省略或为 `0` 时默认为 `100`。此端点不强制执行明确的最大值。
`searchByName`	string	否	针对模板名称或其代码的子字符串匹配 (`like %value%`) — 任一匹配即可。
`searchByLabel`	string	否	标签上的子字符串匹配 (`like %label%`)，或者当 `strictSearchByLabel` 为 `true` 时进行精确匹配。
`strictSearchByLabel`	boolean	否	对 `searchByLabel` 使用精确匹配而不是子字符串匹配。
`searchByCategory`	array of strings	否	重复该参数以按多个类别中的任何一个进行筛选，例如 `?searchByCategory=lifecycle&searchByCategory=promo`。

响应

字段	类型	描述
`email_templates`	array of objects	当前页的电子邮件模板对象。每个项目的 `content` 均为 `null`。
`page`	integer	返回的页面索引。
`per_page`	integer	此响应使用的页面大小。
`total`	integer	匹配筛选条件的所有页面上的模板总数。

响应示例

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

获取

按代码返回单个电子邮件模板，包括发件人信息、各区域设置的主题以及完整的编辑器内容。

GET /api/email_templates/{code}

路径参数

参数	类型	描述
`code`	string	模板的代码（其连接的电子邮件预设代码）。

查询参数

参数	类型	必填	描述
`includeHtml`	boolean	否	是否在编辑器内容旁边返回渲染的 `html`。默认为 `true`。设置为 `false` 可跳过它——它通常占有效负载的一半以上，并且编辑器内容已经描述了模板。

响应

返回 { "email_template": { ... } }，即完整的电子邮件模板对象。

更新

按代码更新现有电子邮件模板，覆盖提供的字段。

PUT /api/email_templates/{code}

路径参数

参数	类型	描述
`code`	string	要更新的模板代码。

请求体

参数	类型	必填	描述
`name`	string	否	新名称，1–255 个字符。省略以保留当前名称。
`content`	object	否	新的电子邮件内容对象，完全替换存储的内容。省略以保持内容不变。
`label`	string	否	新标签。总是被覆盖——省略或发送 `""` 以清除它。
`categories`	array of strings	否	新的全套类别名称。省略以保持类别不变；发送 `[]` 以清除它们。
`previewSettings`	object	否	新的预览设置。省略以保持不变。

请求示例

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

响应

返回 { "email_template": { ... } } — 更新后的电子邮件模板对象，同样不包含 content。如果您需要读回内容，请调用 Get。

删除

按代码删除电子邮件模板及其连接的预设，移除存储的内容。

DELETE /api/email_templates/{code}

路径参数

参数	类型	描述
`code`	string	要删除的模板代码。

响应

成功时返回一个空对象：{}。

克隆

将电子邮件模板——其内容和预设——克隆到目标应用程序中，可选择使用新名称。

POST /api/email_templates:clone

请求体

参数	类型	必填	描述
`emailPresetCode`	string	是	要克隆的模板的 `code`（由 `Create`、`Get`、`List` 或 `Update` 返回）。此处命名为 `emailPresetCode` 是因为它是连接的电子邮件预设的代码——参见约定。
`application`	string	是	目标应用程序代码。可以是同一个应用程序，也可以是同一帐户拥有的不同应用程序。
`name`	string	否	克隆的名称，1–255 个字符。默认为源模板的名称。

请求示例

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

响应

字段	类型	描述
`email_preset_code`	string	新模板的 `code` — 与 `Get`/`Update`/`Delete` 调用的 `code` 标识符相同。

对象参考

下面的字段名称与 Get、List、Update 和 Create 实际返回的名称相匹配——snake_case proto 字段名（参见约定）。当您在请求体（Create、Update）中发回这些相同的结构时，上面请求示例中使用的 lowerCamelCase 形式也有效；服务器接受任一大小写的输入。

电子邮件模板对象

字段	类型	描述
`code`	string	连接的电子邮件预设的代码。在 API 的其他任何地方都用此代码标识该模板。
`name`	string	模板名称。
`label`	string	自由文本标签。
`categories`	array of strings	类别名称。
`content`	object	电子邮件内容对象。仅由 `Get` 填充；在 `Create`、`List` 和 `Update` 响应中为 `null`。
`preview_settings`	object	任意编辑器预览设置。
`created`	string (RFC 3339)	创建时间戳。
`updated`	string (RFC 3339)	最后更新时间戳。

电子邮件内容对象

字段	类型	描述
`sender_info`	object	发件人信息对象 — `from` 和 `reply_to` 地址。
`subject`	object (map)	各区域设置的主题，例如 `{ "en": "Subject", "default": "Subject" }`。
`unlayer` / `pushwoosh` / `smartcards`	object	编辑器内容。必须且只能设置其中一个——它选择哪个编辑器生成（并将渲染）该模板。参见下面的编辑器类型。

编辑器类型

类型	字段	必填子字段	描述
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	拖放式块编辑器 (Unlayer)。`editor_config` 是 Unlayer 设计 JSON。
`pushwoosh`	`html`, `localization_data`	`localization_data`	Pushwoosh 自有的基于 HTML 的编辑器。推荐用于通过编程/API 创作的模板。
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Smart Cards 块编辑器；`content` 是其编辑器特定的 JSON。

在每种类型中，html 都是渲染后的输出。localization_data 是该编辑器自己的各区域设置内容：一个以区域设置代码（en、es、default 等）为键的对象，其中每个值都是该区域设置的编辑器字段副本。其内部结构是编辑器特定的，对本 API 不透明——API 按原样存储和返回它。对于每种类型，在 Create/Update 时都是必需的（如果没有要本地化的内容，请发送 {}）。

每当 API 返回 content 时（目前只有 Get，因为 Create 和 Update 不会回显它），它保证一个区域设置会以 default 的形式暴露出来：如果您自己没有发送 default 键，它会将 en（或者，如果失败，则取第一个区域设置键）提升为 default，并重命名它——您发送的其他所有区域设置都保持原样。subject 也会得到同样的处理。这与 Clone 不同，后者只保留那个默认区域设置的值，并丢弃其余的。

此重命名仅在构建响应时应用——但在写入时不会撤销。如果您按原样获取一个 Get 响应并直接发送到 Update，那么被提升的键（例如 en）现在就变成了字面上的 default，并且 Update 会完全按照您发送的内容进行存储：原始的 en 键从此就永久消失了。如果您需要保留原始的区域设置键，请在调用 Update 之前自己将其从 default 重命名回去。

html 或 localization_data 值内的文本可以包含动态内容标签，例如 {name|string|there} — 这些标签在实际发送电子邮件时会根据收件人的设备标签进行解析。本 API 不会解析它们；它只是存储并返回您放入的任何文本。

发件人信息对象

字段	类型	描述
`from`	object	`{ "email": string, "name": string }` — 发件人地址。
`reply_to`	object	`{ "email": string, "name": string }` — 回复地址。

两个 email 子字段在非空时都必须是有效的电子邮件地址。

电子邮件模板 API

基本 URL

身份验证

约定

错误响应

端点

创建

请求体

请求示例

响应

列表

查询参数

响应

响应示例

获取

路径参数

查询参数

响应

更新

路径参数

请求体

请求示例

响应

删除

路径参数

响应

克隆

请求体

请求示例

响应

对象参考

电子邮件模板对象

电子邮件内容对象

编辑器类型

发件人信息对象

相关内容