使用模板和变量

邮件模板用于保存可重复使用的主题和 HTML 内容。发送时，邮件产品 根据模板 ID 读取当前可用版本，并将请求中的变量替换到主题和正文中。

适用场景

• 多个业务流程重复使用相同邮件结构；
• 需要在主题或正文中插入订单号、验证码、姓名等动态内容；
• 由客户运营人员在控制台维护邮件内容；
• 群发活动复用已审核的营销或事务模板。

如果每封邮件的结构完全由业务系统生成，也可以直接提交 text 或 html，无需使用模板。

创建模板

模板状态

公共模板由平台提供。客户可以查看或复制公共模板，但不能直接修改其原始内容。

变量语法

变量使用双花括号：

Hello {{firstName}}, your order {{orderNo}} has been confirmed.

变量名必须以英文字母开头，后续可以包含字母、数字、下划线、点和连字符，最长 64 个字符。

{{firstName}}
{{order_no}}
{{user.name}}
{{campaign-id}}

点号是变量名的一部分。{{user.name}} 对应变量对象中的 "user.name" 键，不会自动读取嵌套对象。

模板只支持字面量替换，不支持条件、循环或表达式。变量值会转换为字符串；写入 HTML 的动态值应由调用方正确转义。

使用 API 发送模板邮件

{
  "from": {"email": "notify@example.com", "name": "Example"},
  "to": [{"email": "alice@example.net"}],
  "subject": "Order {{orderNo}} confirmed",
  "messageType": "TRANSACTIONAL",
  "variables": {
    "customerName": "Alice"
  },
  "template": {
    "templateId": "tpl_order_confirmation",
    "variables": {
      "orderNo": "ORDER-20261111-001"
    }
  }
}

请求规则：

• subject 仍然必填，并可以包含变量；
• 使用 template 时，不得同时提供非空 text 或 html；
• 顶层 variables 提供通用变量；
• template.variables 中的同名变量优先于顶层变量；
• messageType 必须与模板用途一致；
• template.language 是预留字段，当前不会自动选择其他语言模板，建议省略。

缺失变量

营销模板可以使用 {{unsubscribe_url}}，也兼容 {{unsubscribe}}。详见营销邮件与退订。

结果判断

API 返回受理成功时，模板邮件仍可能在后续阶段失败，例如：

• 模板已停用或被删除；
• 当前版本未审核通过；
• 模板用途与 messageType 冲突；
• 事务模板缺少必需变量；
• 营销模板的退订配置不完整。

请使用 Message ID 查询发送记录与状态。

常见问题

为什么传入 variables 后正文没有变化？

只有模板模式会执行变量替换。直接提交的 text 和 html 由调用方完全控制，不会自动渲染。

为什么审核通过的模板仍然不能发送？

确认模板已启用，当前内容没有在审核后再次修改，并且审核版本与当前版本一致。

是否支持通过 API 上传附件？

当前没有可用的附件内容上传和投递能力。请求模型中的附件引用是预留字段，不会形成实际附件。

相关资源