sales-postmark

Postmark 平台帮助

帮助用户解答 Postmark（ActiveCampaign）平台相关问题，涵盖通过 REST API 和 SMTP 中继发送事务性邮件，以及消息流、Handlebars 模板、收件邮件、Webhooks、DMARC 监控、退信管理、抑制名单、统计信息和集成。Postmark 专注于事务性邮件，提供一流的送达率（98.7% 的收件箱送达率）。该平台最初由 Wildbit（Natalie 和 Chris Nagele）打造，并于 2022 年被 ActiveCampaign 收购。

步骤 1 — 收集背景信息

如果存在 references/learnings.md，请先阅读，了解积累的知识。

询问用户：

1. 你需要 Postmark 哪方面的帮助？

   • A) 邮件 API — 通过 REST API（POST /email、POST /email/batch）发送事务性邮件，以及 SDK
   • B) SMTP 中继 — 为不支持 API 的框架提供传统 SMTP 集成
   • C) 消息流 — 将事务性邮件与群发邮件（新闻简报／公告）的基础设施分开
   • D) 模板 — 服务端 Handlebars 模板、布局继承、跨服务器推送
   • E) 收件邮件 — 通过 webhook 接收和解析收到的邮件
   • F) Webhooks — 退信、送达、打开、点击、垃圾邮件投诉、订阅变更和收件事件
   • G) DMARC 监控 — 免费的每周 DMARC 报告，以及付费的详细监控
   • H) 退信管理／抑制名单 — 自动处理退信、抑制名单
   • I) 统计信息 — 打开、点击、送达率、退信率、垃圾邮件投诉
   • J) 发件人签名 — 已验证的发件人地址和域名
   • K) 账户／账单 — 方案、定价、服务器、API 令牌
   • L) 其他 — 请描述

2. 你的角色是什么？

   • A) 开发人员／工程师
   • B) DevOps／基础设施
   • C) 管理员／账户所有者
   • D) 创始人／独立运营者
   • E) 代理机构／自由职业者
   • F) 其他

3. 你想要实现什么？（描述你的具体目标或问题）

如果用户的请求已经提供了大部分背景信息，请直接进入相关步骤。 基于合理假设（并明确说明假设），先尽力回答，然后只在最后提出最关键的 1 到 2 个澄清问题；不要因为需要收集完整背景信息而延迟回复。

注意：如果用户需要专门的技能，请简要说明该技能为何更合适，并引导用户前往。

步骤 2 — 引导或直接回答

如果请求对应某项专门技能，请引导用户前往：

• 通用邮件营销策略／最佳实践 -> /sales-email-marketing
• 跨平台邮件送达率（非 Postmark 专属）-> /sales-deliverability
• 邮件打开／点击跟踪策略 -> /sales-email-tracking
• SendGrid 专属问题 -> /sales-sendgrid
• 通过 Zapier 或中间件将 Postmark 连接到其他工具 -> /sales-integration
• 漏斗策略／转化优化 -> /sales-funnel

否则，请根据下方参考资料直接回答平台相关问题。

步骤 3 — Postmark 平台参考资料

阅读 references/platform-guide.md，了解详细的模块文档、定价、集成和数据模型。

无需再了解平台指南的详细内容，专注于用户的具体情况。

第 4 步 — 可执行指南

根据用户的具体问题：

1. 通过 API 发送事务性邮件：

   1. 在 Postmark 界面中创建一个服务器（或使用默认服务器）
   2. 从服务器的凭据页面复制 Server API Token
   3. 添加并验证 Sender Signature——可以是单个电子邮件地址，也可以是整个域名（在 DNS 中添加 DKIM 和 Return-Path CNAME 记录）
   4. 安装适用于你所用语言的 SDK（例如，Node.js 使用 npm install postmark）
   5. 初始化客户端：const client = new postmark.ServerClient("YOUR_SERVER_TOKEN")
   6. 发送电子邮件：设置 From、To、Subject、HtmlBody/TextBody（或使用 TemplateId + TemplateModel）
   7. 处理响应——检查 ErrorCode: 0（成功）或特定错误代码
   8. 开发期间使用 POSTMARK_API_TEST 作为服务器令牌进行测试，而不发送真实邮件

2. 为事务性邮件和群发邮件设置 Message Streams：

   1. 在 Postmark 界面中导航到你的服务器
   2. 默认的事务性流已存在——将其用于密码重置、收据和提醒
   3. 创建新的群发流：Servers > [Your Server] > Message Streams > Add Stream > Broadcast
   4. 为流命名（例如，“Newsletter”“Product Updates”）
   5. 在 API 调用中传入 "MessageStream": "your-broadcast-stream-id"，以便将邮件发送到群发流
   6. 如有需要，为每个流配置单独的 Webhook
   7. 分别监控每个流的统计数据，以跟踪发件人声誉状况

3. 设置支持布局继承的 Handlebars 模板：

   1. 首先创建布局模板：Templates > Add Template > Layout
   2. 在布局中定义 {{{@content}}} 占位符，内容模板将插入此处
   3. 在布局中加入共享元素：页眉、页脚、样式和取消订阅链接
   4. 创建通过 LayoutTemplate 字段引用布局的内容模板
   5. 在内容模板中使用 Handlebars 语法：{{variable}}、{{#if condition}}、{{#each items}}
   6. 使用示例数据通过 API 验证模板（POST /templates/{id}/validate）
   7. 通过 Template Push API 在服务器之间推送模板（从暂存环境推送到生产环境）

4. 处理入站邮件：

   1. 升级到 Pro 方案或更高级别（Developer 和 Basic 方案不支持入站邮件）
   2. 为接收邮件的域名添加 MX 记录：10 inbound.postmarkapp.com
   3. 在 Postmark 界面的服务器 Inbound 设置中配置入站 Webhook URL
   4. 还可设置入站规则，以筛选会触发 Webhook 的收件人地址
   5. 实现 Webhook 端点，以接收包含已解析字段（From、To、Subject、HtmlBody、TextBody、Attachments）的 JSON 负载
   6. 处理附件——它们以 base64 编码内容的形式包含在 JSON 负载中
   7. 端点返回 200 状态码以确认收到

5. 设置 DMARC 监控：

   1. 为你的域名添加 DMARC DNS 记录：v=DMARC1; p=none; rua=mailto:[email protected]
   2. 系统会自动开始发送免费周报摘要，汇总哪些发件方在使用你的域名发送邮件
   3. 如需详细监控（每个域名每月 $14），请前往 dmarc.postmarkapp.com 注册
   4. 查看报告，找出未经授权的发件方以及 SPF/DKIM 对齐失败的情况
   5. 确认所有合法发件方都已通过身份验证后，逐步收紧 DMARC 策略：p=none -> p=quarantine -> p=reject

注意事项

根据调研整理的尽力而为版本 — 请对照 Postmark 当前文档核实详情。

1. 专用 IP 要求每月至少发送 300K 封邮件。 与 SendGrid 或 Mailchimp 不同，后两者允许在发送量较低时购买专用 IP；Postmark 要求持续保持较高发送量，以维护 IP 声誉。如果每月发送量少于 300K 封，Postmark 的共享 IP 池实际上能带来更好的投递效果——其发件人审核流程让共享 IP 声誉保持在极高水平。不要想当然地认为专用 IP 就更好。
2. 入站邮件仅适用于 Pro 套餐及更高级别。 如果需要接收并解析收到的邮件（回复处理、支持工单、邮件转应用工作流），Developer 和 Basic 套餐都无法满足需求。如果架构中包含入站邮件，请至少按 Pro 套餐（$16.50/月）编列预算。
3. 事务邮件流和群发邮件流有各自独立的抑制列表，但费用合并计算。 尽管 Message Streams 会隔离发送声誉，抑制列表按邮件流分别维护——在群发邮件流中被抑制的地址仍可收到事务邮件，反之亦然。这是有意为之（用户退订新闻简报后仍应收到密码重置邮件），但可能会让原以为存在统一全局抑制列表的团队感到意外。
4. Postmark 有发件人审核流程——不能立即进行大批量发送。 新账户需要经过审批。Postmark 会审核你的使用场景，并可能询问发送模式、受众和内容。正是这一审核流程让其共享 IP 声誉保持在极高水平，但这也意味着你不能注册后第一天就群发 100K 封邮件。新账户请预留 1-2 个工作日的审批时间。
5. DMARC 监控 API 与 Postmark 主 API 完全独立。 DMARC 服务位于 dmarc.postmarkapp.com，使用单独的身份验证令牌和端点。调用 DMARC API 时，不要使用 Postmark 服务端令牌或账户令牌——尽管两者都是 Postmark 产品，但它们属于使用不同凭据的独立系统。

• 持续改进：如果发现此处未涵盖的内容，请附上今天的日期，将其添加到 references/learnings.md。

步骤 5 — 相关技能

• /sales-email-marketing — 电子邮件营销策略和最佳实践（与平台无关）
• /sales-deliverability — 跨平台电子邮件投递能力——SPF/DKIM/DMARC、预热、收件箱送达
• /sales-email-tracking — 电子邮件打开和点击跟踪策略
• /sales-sendgrid — SendGrid 平台帮助——如果需要 SendGrid 专属指导，请使用此项
• /sales-integration — 通过 Zapier、Make 或 API 将 Postmark 连接到其他工具
• /sales-do — 不确定该使用哪项技能？路由器会根据任何销售目标匹配合适的技能。安装：npx skills add sales-skills/sales --skill sales-do

示例

示例 1：为 Rails 应用设置事务邮件

用户说：“我需要通过 Postmark 从 Rails 应用发送订单确认和发货通知邮件。” 技能执行：

1. 指导创建 Postmark 服务端并复制 Server API Token
2. 演示如何添加并验证 Sender Signature——在 DNS 中添加 DKIM 和 Return-Path CNAME 记录
3. 演示如何配置 Action Mailer，通过 Postmark 的 SMTP 中继发送邮件（smtp.postmarkapp.com，端口 587，令牌同时作为用户名和密码）
4. 或者，建议使用 postmark-rails gem 进行原生 API 集成，以获得比 SMTP 更好的错误处理
5. 创建两个共用布局（页眉/页脚）的 Handlebars 模板——一个用于订单确认（包含 {{order_number}}、{{items}}），另一个用于发货通知（包含 {{tracking_url}}）
6. 建议设置 Delivery 和 Bounce Webhook，以跟踪发送失败并触发客户服务提醒 结果：用户拥有可用于生产环境的事务邮件，包含模板、共用布局、适当的身份验证和投递监控

示例 2：将新闻简报与事务性邮件分开

用户说：“我们通过 Postmark 同时发送密码重置邮件和每周新闻简报。新闻简报的退订正在影响事务性邮件的送达率。” 技能会：

1. 说明 Message Streams——广播邮件的发件人信誉正在影响事务性邮件流，因为他们很可能通过默认的事务性邮件流发送所有邮件
2. 指导创建新的新闻简报广播流
3. 更新新闻简报发送代码，在 API 调用中加入 "MessageStream": "newsletter"
4. 为每个流配置单独的 Webhook——事务性邮件使用退信／送达 Webhook，广播邮件则额外配置订阅变更 Webhook
5. 说明抑制名单按流区分，因此退订新闻简报的用户仍会收到事务性邮件（密码重置邮件、收据）
6. 迁移后检查广播流统计数据，确认垃圾邮件投诉率降至 0.1% 以下 结果：广播邮件的信誉问题被限制在新闻简报流中，用户的事务性邮件送达速度得以恢复

示例 3：为支持工单系统设置入站邮件

用户说：“我们希望客户可以回复支持邮件，并让这些回复自动在我们的系统中创建或更新工单。” 技能会：

1. 确认用户使用的是 Pro 套餐或更高级别的套餐（入站邮件的要求）——如果不是，则建议从 Basic（$15）升级到 Pro（$16.50）
2. 指导为支持域名（例如 support.company.com）添加一条指向 inbound.postmarkapp.com 的 MX 记录
3. 在 Postmark 服务设置中配置入站 Webhook URL
4. 设置入站规则，仅接受发送到特定地址的邮件（例如 *@support.company.com）
5. 设计 Webhook 端点：解析 JSON 负载，提取 From、Subject、TextBody，以及从 In-Reply-To 标头或 To 地址中的标签提取原始工单 ID
6. 将入站邮件映射到现有工单（更新），或在找不到匹配项时创建新工单 结果：用户拥有了可正常运作的“回复邮件转工单”流程，客户的邮件回复会自动进入其支持系统

故障排查

邮件因错误代码 406（收件人已停用）遭拒

症状：API 调用针对应当有效的地址返回错误代码 406：“您尝试发送邮件的收件人已被标记为非活动状态” 原因：该收件人之前发生过硬退信或提交过垃圾邮件投诉，Postmark 已自动将其添加到该消息流的抑制名单中。Postmark 会阻止后续发送，以保护发件人信誉。 解决方案：通过 API（GET /message-streams/{stream}/suppressions/dump）或在界面的 Suppressions 页面中，检查相关消息流的抑制名单。如果根本问题已解决（例如，收件人的邮箱曾满，现在已恢复正常），则通过删除抑制记录重新激活该地址（在请求正文中提供电子邮件地址，调用 POST /message-streams/{stream}/suppressions/delete）。对于硬退信，请先确认地址有效再重新激活——如果再次向会退信的地址发送邮件，该地址会再次被加入抑制名单。

Webhook 端点接收重复事件

症状：Webhook 端点多次处理同一事件，导致系统中出现重复记录或重复操作。 原因：如果端点未能在超时时间内返回 2xx 状态码，或投递期间发生网络中断，Postmark 会重试投递 Webhook。重试时会再次发送相同的事件负载。 解决方案：让 Webhook 处理程序具备幂等性——使用 Webhook 负载中的 MessageID 字段作为去重键。处理前，检查是否已处理过该 MessageID 和事件类型对应的事件。将已处理的事件 ID 存储在缓存或数据库中。确保端点能快速返回 200 状态码（几秒内）——将耗时处理移至后台队列。如果重试次数过多，请检查端点的响应时间和错误率。

模板未能渲染变量（显示原始 Handlebars 标签）

症状：发送的邮件显示字面文本 {{variable_name}}，而不是渲染后的值。 原因：API 调用未正确传递模板模型数据，或者模板中的变量名与 TemplateModel 对象中的键不匹配。另一个常见原因是使用了 POST /email（原始发送），而不是 POST /email/withTemplate（模板发送）。 解决方案：确认使用的是模板发送端点（POST /email/withTemplate），并传入 TemplateId（或 TemplateAlias）以及包含正确变量名的 TemplateModel。变量名区分大小写——{{OrderNumber}} 要求模型中使用 "OrderNumber"，而不是 "orderNumber"。发送前，使用模板验证端点（POST /templates/{id}/validate）通过示例数据测试渲染效果。查看 Postmark Activity 日志中的渲染后邮件，确认实际发送的内容与预期是否一致。