邮件模板 API 指南（2026）：创建、发布与变量发送

本文覆盖什么

Rovela 模板把 HTML / 纯文本正文从部署路径里抽出来：创建一次命名模板，之后发送只带模板 id 和 variables。本文是开发者 API 生命周期——创建、列表、获取、更新、发布、复制、删除与发送——对齐线上 Templates API 与 邮件模板指南。

这不是 用模板发欢迎邮件（注册流程 + Idempotency-Key）。也不是 HTML 邮件模板开发（表格、内联 CSS、客户端兼容）。更不是 欢迎邮件最佳实践（主题、CTA、引导文案）。相关文：发票 PDF 附件、Next.js 魔法登录。

密钥：full_access 与 sending_access

模板管理——POST /templates、GET、PATCH、POST …/publish、POST …/duplicate、DELETE——需要 full_access API key 或控制台会话。sending_access 在这些路由上会得到 403（Templates API、Authentication）。

用 template: { id, variables } 调 POST /emails 发信，只需 sending_access。管理密钥不要放进生产 worker；两种密钥都不要打进浏览器包。

前置条件

1. 已验证的发信域名（Quick Start）。
2. 管理操作用的 full_access key。
3. 生产发送用的 sending_access（例如环境变量 ROVELA_API_KEY）。
4. 存放模板 UUID 的地方（环境变量或自有配置）。

创建模板

POST /templates 需要 name、subject，以及 html / text 至少其一。能同时给两种正文更好：HTML 给多数客户端，纯文本给纯文本客户端、部分无障碍场景和反垃圾信号（邮件模板指南）。

curl -X POST https://api.rovela.dev/templates \
  -H "Authorization: Bearer re_your_full_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order receipt",
    "subject": "Your order {{order_id}} is confirmed",
    "html": "<h1>Thanks, {{name}}</h1><p>Order <strong>{{order_id}}</strong> is confirmed.</p>",
    "text": "Thanks, {{name}}. Order {{order_id}} is confirmed."
  }'

保存返回的 id（UUID）。后续发送与管理都靠它。

变量规则（{{name}}）

占位符写作 {{name}}——两层花括号夹变量名——在发送时用 variables 对象替换（Templates API）。

• 键名精确匹配。 {{UserName}} 与 {{userName}} 是不同变量。
• 不做自动转义。 值按原样插入。用户输入进 variables 前先做 HTML 转义，否则像 <img src=x> 这样的显示名会变成邮件里的标记。
• 缺键保持字面量。 未传入的键会原样留下 {{name}}，不会变成空字符串。这样投递出来的邮件能直接暴露 bug，而不是出现「Thanks, .」。
• 没有条件与循环。 模板语言只有替换。需要逻辑时，在应用里渲染 HTML，改发 html，不要用 template。

列表与获取

# 列表 —— 收集发送与后台用的 id
curl https://api.rovela.dev/templates \
  -H "Authorization: Bearer re_your_full_access_key"

# 单个模板 —— 正文、主题与元数据
curl https://api.rovela.dev/templates/<template_uuid> \
  -H "Authorization: Bearer re_your_full_access_key"

更新（PATCH）

PATCH /templates/:id 可更新 name、subject、html 或 text。省略的字段保持不变。

curl -X PATCH https://api.rovela.dev/templates/<template_uuid> \
  -H "Authorization: Bearer re_your_full_access_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Receipt for order {{order_id}}",
    "html": "<h1>Thanks, {{name}}</h1><p>Order {{order_id}} is confirmed. Total: {{total}}.</p>"
  }'

编辑线上模板时注意

编辑会改变下一次发送渲染的内容。已发出的邮件保留当时渲染结果。尚未触发的定时发送会用上新正文。若这有风险，先 duplicate，改副本，再把生产指向新 id（Templates API、邮件模板指南）。

发布

模板有 published 状态。发布是独立、幂等的调用——对已发布模板再 publish 不会改动首次上线时间戳。

curl -X POST https://api.rovela.dev/templates/<template_uuid>/publish \
  -H "Authorization: Bearer re_your_full_access_key"

复制

需要变体、又不想改生产正在用的模板时用 duplicate。

curl -X POST https://api.rovela.dev/templates/<template_uuid>/duplicate \
  -H "Authorization: Bearer re_your_full_access_key"

改副本、按流程 publish，再把发送路径切到新 id。

删除

curl -X DELETE https://api.rovela.dev/templates/<template_uuid> \
  -H "Authorization: Bearer re_your_full_access_key"

已发出的邮件仍保留渲染内容。之后仍引用该 id 的发送会失败。

用模板发送

template 与 html / text 互斥。主题来自模板，用同一套 variables 渲染；发送请求上的 subject 会被忽略。按收件人变化的主题应写成模板变量（Templates API）。

curl -X POST https://api.rovela.dev/emails \
  -H "Authorization: Bearer re_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": "alice@example.com",
    "template": {
      "id": "<template_uuid>",
      "variables": {"name": "Alice", "order_id": "A-10422", "total": "$42.00"}
    }
  }'

批量接口不允许 template

POST /emails/batch 会直接拒绝 template，而不是静默忽略。若批量条目悄悄丢掉正文，就会发出空信。批量个性化请对每位收件人单独 POST /emails + template，或自行渲染后在批量条目里传 html / text（Templates API）。

推荐工作流

1. 用 full_access 创建（POST /templates），尽量同时带 html 与 text。
2. 用 sending_access 先发给自己测一遍，再接生产（邮件模板指南）。
3. 若流程需要记录上线时间，再 publish。
4. 改线上文案：优先 复制 → 编辑 → 测试 → 切换 id，避免在定时发送尚未触发时直接 PATCH 生产 id。
5. 热路径只用 sending_access；full_access 留在配置/运维侧。

什么时候不用模板

一次性邮件，或发送时才有、且带分支逻辑的正文，跳过模板：在应用里渲染后直接传 html（邮件模板指南）。

延伸阅读

• Templates API — 端点与变量规则
• Email templates — 何时抽模板、如何自测
• Send emails — POST /emails 字段
• 用模板发欢迎邮件 — 注册场景 walkthrough
• Authentication — 密钥权限范围