用途
本技能用于通过 Postmark 发送事务性邮件或广播邮件，覆盖单封发送、批量发送（最多 500 封）、群发以及基于服务端模板的邮件。
主要能力
Postmark 提供多个发送端点：
- 单封发送：POST /email，适用于单封事务性邮件，限制 1 封邮件、含附件 10 MB。
- 批量发送：POST /email/batch，一次请求最多 500 封，含附件 50 MB。
- 模板发送：POST /email/withTemplate，使用服务端 Handlebars 模板，限制 1 封、10 MB。
- 批量模板发送：POST /email/batchWithTemplates，最多 500 封、50 MB。
- 群发：POST /email/bulk，用于广播流活动，无固定收件人上限，含附件 50 MB。
选择建议：需要一次发送 2 封以上不同邮件、注重性能或需要附件时选批量；发送单封或需要实时逐条错误处理时选单封。
消息流（关键）
Postmark 按用途区分邮件，必须始终指定 MessageStream：
- Transactional（事务性）：值 outbound，用于 1:1 触发邮件（默认），SMTP 端点 smtp.postmarkapp.com。
- Broadcast（广播）：值 broadcast，用于营销、新闻通讯，SMTP 端点 smtp-broadcasts.postmarkapp.com。
切勿在同一流中混用事务性与广播邮件，否则会损害送达率。每个服务器最多可有 10 个消息流。
使用方式
快速开始：从 Postmark 服务器设置获取 API Token；验证发件域名或邮箱地址；安装 SDK（见 references/installation.md）；根据决策矩阵选择端点。
认证：所有 API 请求需要 Server API Token，通过请求头 X-Postmark-Server-Token 传递。将令牌存储在 POSTMARK_SERVER_TOKEN 环境变量中。测试而不实际发送时，使用 POSTMARK_API_TEST 作为令牌值。
单封邮件：端点 POST https://api.postmarkapp.com/email。必填参数包括 From（发件地址，须为已验证域名或发件签名）、To（收件人，逗号分隔，含 Cc/Bcc 最多 50 个）、Subject、TextBody 或 HtmlBody（至少一个）。可选参数包括 Cc、Bcc、ReplyTo、MessageStream、Tag、Metadata、TrackOpens、TrackLinks、Headers、Attachments。
示例代码：
const postmark = require('postmark');
const client = new postmark.ServerClient(process.env.POSTMARK_SERVER_TOKEN);
const result = await client.sendEmail({
From: 'notifications@yourdomain.com',
To: 'customer@example.com',
Subject: 'Your order has shipped',
TextBody: 'Your order #12345 is on its way!',
HtmlBody: '<p>Your order <strong>#12345</strong> is on its way!</p>',
MessageStream: 'outbound',
Tag: 'order-shipped'
});
console.log('MessageID:', result.MessageID);
响应包含 MessageID，可用于通过 webhook 或 Messages API 跟踪。
批量邮件：端点 POST https://api.postmarkapp.com/email/batch。一次 API 调用最多发送 500 封，每封独立验证，可有各自的附件、标签和元数据。超过 500 封时，将数组按 500 分组并顺序发送。务必处理部分失败。
模板发送：端点 POST https://api.postmarkapp.com/email/withTemplate。使用服务端 Handlebars 模板，无需客户端渲染。始终使用 TemplateAlias 而非 TemplateId，别名在重新创建后仍有效且跨环境可用。批量模板发送（最多 500 封）使用 POST /email/batchWithTemplates。
附件：以 Base64 编码内容包含。内联图片使用 ContentID。大小限制：TextBody/HtmlBody 各 5 MB；单封含附件 10 MB；批量负载 50 MB；Base64 编码增加约 33%；某些文件类型被阻止（.exe、.bat）。
跟踪：可按邮件或服务器级别配置 TrackOpens 和 TrackLinks。TrackLinks 选项：None | HtmlAndText | HtmlOnly | TextOnly。对敏感事务性邮件（密码重置、安全警报）应禁用跟踪以最大化送达率。
测试：可使用 API 测试令牌 POSTMARK_API_TEST（验证请求但不发送）、黑洞地址 test@blackhole.postmarkapp.com（丢弃但出现在活动中）、沙箱服务器（完整处理但不投递）、硬退信地址 hardbounce@bounce-testing.postmarkapp.com、软退信地址 softbounce@bounce-testing.postmarkapp.com。切勿在真实提供商处使用假地址（如 test@gmail.com）测试，会损害发件人声誉。
错误处理：200 成功继续；401 未授权检查 API 令牌不重试；406 收件人未激活检查抑制列表不重试；409 需要 JSON 修正请求头；410 批量消息过多减少到 500 或更少；413 负载过大减少负载；422 验证错误修正参数不重试；429 速率限制使用指数退避重试；500 服务器错误使用指数退避重试。
SMTP：Postmark 支持 SMTP 用于旧式集成，主机 smtp.postmarkapp.com（事务性）或 smtp-broadcasts.postmarkapp.com（广播），端口 25/2525/587，用户名和密码均为 Server API Token。
适用场景
适用于需要通过 Postmark 发送事务性邮件（如订单通知、密码重置）或广播邮件（如营销、新闻通讯）的开发者与团队，尤其适合需要批量发送、模板化内容、附件或跟踪功能的场景。
限制
- From 地址必须使用已验证域名或发件签名。
- 每封邮件收件人总数最多 50 个（To + Cc + Bcc）。
- 单封含附件 10 MB，批量负载 50 MB。
- 批量发送最多 500 封。
- 新域名需要逐步增加发送量进行预热（参见 postmark-email-best-practices）。
- 某些文件类型被阻止（.exe、.bat）。
- 事务性与广播邮件不得混用同一消息流。