Postmark 模板是使用 Handlebars 语法的服务端邮件模板。模板在 Postmark 的服务器上渲染，无需客户端渲染库。
用途 用于创建、管理和发送 Postmark 服务端邮件模板，支持 Handlebars 语法、布局继承、模板校验，以及在服务器之间推送模板。
主要能力
- 语法：Handlebars（兼容 Mustache）。
- 渲染：服务端渲染，无需 React，无需客户端库。
- 类型：标准模板（Standard）与布局模板（Layout）。
- 继承：标准模板可继承自某个布局。
- 校验：提供 API 端点，可在发送前测试渲染模板。
- 跨服务器：可在服务器之间推送模板（例如从预发环境到生产环境）。
- 限制：每个服务器默认最多 100 个模板（如需更多请联系支持）。
快速开始
- 通过 API 或 Postmark 仪表盘创建模板。
- 使用 Handlebars 语法定义变量：{{variable_name}}。
- 使用模板发送：POST /email/withTemplate 或 POST /email/batchWithTemplates。
- 通过 TemplateModel 传入数据，由 Postmark 渲染并发送。
模板语法（Handlebars） Hello {{name}} {{! variable}} {{{html_content}}} {{! unescaped HTML}} {{#if premium}}Premium member{{/if}} {{! conditional}} {{#each items}}{{this.name}}{{/each}} {{! iteration}} {{customer.address.city}} {{! nested object}}
模板类型
- Standard（TemplateType 为 "Standard"）：可发送，定义主题、HTML 与文本正文。
- Layout（TemplateType 为 "Layout"）：不可直接发送，是可复用包装层，通过 {{{@content}}} 注入内容。标准模板可通过 LayoutTemplate: "layout-alias" 引用某个布局；发送时，标准模板的正文会替换布局中的 {{{@content}}}。
API 端点 模板 CRUD：
- POST /templates：创建新模板。
- GET /templates：列出全部模板（?count=100&offset=0&templateType=Standard）。
- GET /templates/{idOrAlias}：获取单个模板。
- PUT /templates/{idOrAlias}：更新模板。
- DELETE /templates/{idOrAlias}：删除模板。
- POST /templates/validate：校验模板渲染。
- PUT /templates/push：将模板推送到另一个服务器。
使用模板发送：
- POST /email/withTemplate：使用模板发送单封邮件。
- POST /email/batchWithTemplates：使用模板批量发送（最多 500 封）。
使用模板发送示例 建议优先使用 TemplateAlias 而非 TemplateId —— 别名在模板重建后仍有效，并可跨环境使用：
const postmark = require('postmark'); const client = new postmark.ServerClient(process.env.POSTMARK_SERVER_TOKEN);
await client.sendEmailWithTemplate({ From: 'hello@yourdomain.com', To: 'customer@example.com', TemplateAlias: 'welcome-email', TemplateModel: { name: 'Jane Doe', product_name: 'Acme App' }, MessageStream: 'outbound' });
校验模板 在不发送的情况下测试渲染，适合在部署模板变更前的 CI/CD 中使用：
const validation = await client.validateTemplate({ Subject: 'Welcome {{name}}', HtmlBody: '<h1>Hello {{name}}</h1>', TextBody: 'Hello {{name}}', TestRenderModel: { name: 'Test User' } });
console.log('Valid:', validation.AllContentIsValid); console.log('Rendered:', validation.Subject.RenderedContent);
常见错误与修正
- 用 {{html}} 输出 HTML 内容：应使用三重花括号 {{{html}}} 输出未转义 HTML。
- 布局中忘记 {{{@content}}}：布局模板必须包含 {{{@content}}} 占位符。
- 删除仍被依赖的布局：应先解除标准模板与布局的关联。
- 跨环境使用模板 ID：应使用 TemplateAlias，它在重建后仍有效并可跨服务器使用。
- 部署前不校验：使用 /templates/validate 在发送前测试渲染。
- 直接发送布局：布局只是包装层，只能发送标准模板。
- 缺少 TemplateModel 字段：Handlebars 会将缺失变量渲染为空字符串，需校验数据。
- 超过 100 个模板：联系 Postmark 支持以提高每服务器上限。
注意事项
- 模板使用 Handlebars（兼容 Mustache）语法，无需 React 或客户端渲染。
- 模板别名是字符串，模板 ID 是整数；为便于移植，优先使用别名。
- TemplateType 为 Standard（可发送）或 Layout（包装层）。
- 布局继承：标准模板正文替换布局中的 {{{@content}}}。
- 使用 Account Token（而非 Server Token）在服务器之间推送模板。
- 每个服务器默认最多 100 个模板。
- 模板校验（/templates/validate）允许在不发送的情况下测试渲染。
- TemplateId 与 TemplateAlias 均可用于发送，但二者择一，不要同时使用。
适用场景
- 事务性邮件发送（如欢迎邮件、通知邮件）。
- 维护邮件模板库，并借助布局模板统一邮件外观。
- 在部署前通过校验端点验证模板渲染。
- 在预发与生产等不同服务器之间同步模板。
限制
- 每个服务器默认最多 100 个模板，超出需联系支持。
- 布局模板不能直接发送，只能作为包装层。
- 其他未在资料中说明的收费、价格、平台或效果信息暂未提供。