sales-mailgun

Mailgun 平台帮助

帮助用户解答 Mailgun（Sinch）平台相关问题，包括通过 REST API 和 SMTP 中继发送事务性电子邮件，以及入站邮件路由、模板、邮件列表、域名、路由、Webhook、指标和 Mailgun Optimize。Mailgun 是一项以开发者为先的事务性电子邮件 API 服务，由 Ev Kontsevoy 和 Taylor Wakefield 于 2010 年创立，后于 2012 年被 Rackspace 收购、于 2019 年被 Thoma Bravo 收购，并于 2021 年被 Sinch 收购。Josh Odom 是 Sinch 开发者与电子邮件部门的总裁。

第 1 步 — 收集背景信息

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

询问用户：

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

   • A) 电子邮件 API — 通过 REST API（POST /v3/{domain}/messages）或 SMTP 中继发送事务性电子邮件
   • B) SMTP 中继 — 传统 SMTP 集成（端口 25/465/587）
   • C) 入站邮件路由 — 使用自定义规则（正则表达式/JSONPath）接收和解析入站邮件，并通过 Webhook 传送邮件及附件
   • D) 模板 — 账户级和域名级存储模板，支持类似 Handlebars 的变量
   • E) 邮件列表 — 通过程序管理列表和成员的增删改查
   • F) Domains API — 域名管理、DNS 验证、DKIM/SPF 设置
   • G) 路由 — 将入站邮件转发到 HTTP 端点或电子邮件地址，或存储 3 天
   • H) Webhook — 事件通知（accepted、delivered、opened、clicked、permanent_fail、temporary_fail、complained、unsubscribed）
   • I) Metrics API — 分析送达率、互动度和发送状况
   • J) Mailgun Optimize — 收件箱投放位置种子测试、电子邮件验证（单个和批量 CSV）、发件人信誉监控、黑名单提醒
   • K) 标签 — 对发送内容进行分类和追踪
   • L) 账户 / 账单 — 套餐、定价、API 密钥、自定义消息限额
   • M) 其他 — 请描述具体需求

2. 你的角色是什么？

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

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

如果用户的请求已经提供了大部分背景信息，请直接跳到相关步骤。 根据合理假设（并明确说明）尽力先给出答案，然后仅在结尾提出最关键的 1-2 个澄清问题——不要等收集完所有背景信息后才作答。

注意：如果用户需要专门技能，请简要说明该技能更合适的原因，并引导他们前往相应技能。

第 2 步 — 转接或直接回答

如果请求对应某项专门技能，请转接：

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

否则，请根据下方参考内容，直接使用平台知识作答。

第 3 步 — Mailgun 平台参考

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

现在无需再了解平台指南的细节，请专注于用户的具体情况。

步骤 4 — 可执行指南

根据用户的具体问题：

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

   1. 注册 Mailgun 账户，并从控制面板复制 API 密钥
   2. 添加并验证发件域名 — 添加所需的 DNS 记录（MX、包含 include:mailgun.org 的 SPF TXT、DKIM CNAME/TXT）
   3. 等待 DNS 传播完成，然后在 Mailgun 界面中或通过 GET /v3/domains/{domain} 验证域名
   4. 发送第一封邮件：使用 Basic Auth（api:YOUR_API_KEY）调用 POST /v3/{domain}/messages，并传入 from、to、subject 和 text/html 字段
   5. 可选：为生产环境创建 Domain Sending Key — 出于安全考虑，该密钥仅限用于 /messages 端点
   6. 添加标签（o:tag）和自定义变量（v:my-var），用于跟踪和分析
   7. 通过 Events API（GET /v3/{domain}/events）监控投递情况，或设置 Webhook 接收实时通知

2. 设置入站邮件路由：

   1. 为接收邮件的域名添加 MX 记录，并将其指向 Mailgun 的入站服务器
   2. 在 Mailgun 界面中验证域名
   3. 通过 API（POST /v3/routes）或界面创建路由 — 定义匹配表达式和操作
   4. 匹配表达式示例：match_recipient("[email protected]")、match_header("subject", ".*order.*")、catch_all()
   5. 操作示例：forward("https://yourapp.com/webhook")、forward("[email protected]")、store(notify="https://yourapp.com/notify")
   6. 实现 Webhook 端点，以 multipart/form-data 格式接收解析后的邮件（发件人、主题、正文、附件）
   7. 使用正则表达式或 JSONPath 自定义解析规则，实现高级路由逻辑

3. 设置域级模板：

   1. 创建模板：调用 POST /v3/{domain}/templates，并传入名称、描述和初始版本内容
   2. 在模板中使用类似 Handlebars 的变量：{{first_name}}、{{order_number}}、{{items}}
   3. 创建其他版本，用于 A/B 测试或迭代
   4. 使用模板发送邮件：添加 template 参数并填入模板名称，同时添加包含 JSON 数据对象的 h:X-Mailgun-Variables
   5. 通过 Templates API 以编程方式管理模板 — 列出、更新和删除模板

4. 配置用于投递跟踪的 Webhook：

   1. 创建 Webhook：调用 POST /v3/domains/{domain}/webhooks，并传入事件类型（例如 delivered、opened、permanent_fail）和端点 URL
   2. 实现 Webhook 端点以接收 JSON 负载
   3. 使用 API 密钥验证 Webhook 签名 — Mailgun 会对每个 Webhook 进行签名以确保安全
   4. 处理批量投递 — 你的端点可能会在单个 POST 中收到多个事件
   5. 尽快返回 200 状态码 — 将耗时的处理工作移至后台队列
   6. 为全部 8 种事件类型设置 Webhook，以全面掌握情况：accepted、delivered、opened、clicked、permanent_fail、temporary_fail、complained、unsubscribed

5. 使用 Mailgun Optimize 提升送达率：

   1. 订阅 Optimize 附加计划（Pilot 每月 $49，Starter 每月 $99）— 该计划与 Send 计划分开
   2. 运行收件箱送达测试：向 Mailgun 的种子列表发送测试邮件，并查看各邮件服务商的收件箱与垃圾邮件结果
   3. 发送前验证电子邮件地址：GET /v4/address/[email protected] — 返回风险级别（deliverable、undeliverable、risky、unknown）
   4. 上传 CSV 文件以批量验证地址并清理列表
   5. 在 Optimize 控制面板中监控发件人信誉和黑名单状态
   6. 设置黑名单提醒，以便在你的 IP 或域名被列入黑名单时立即收到通知

注意事项

基于调研整理，尽力而为——请核实以下内容，尤其是关于受套餐限制的功能和集成注意事项的条目，这些内容可能已经过时。

1. 美国和欧盟区域需要使用正确的基础 URL，且域名创建后无法切换区域。 美国域名使用 https://api.mailgun.net/v3/，欧盟域名使用 https://api.eu.mailgun.net/v3/。域名创建后，无法迁移到另一个区域。如果你需要满足 GDPR 合规要求的数据驻留在欧盟，请从一开始就在欧盟区域创建域名。使用错误的基础 URL 会返回难以排查的身份验证错误。
2. Mailgun Optimize 是单独付费的附加服务（每月 49 美元起），不包含在任何 Send 套餐中。 收件箱投递位置种子测试、电子邮件验证、发件人信誉监控和阻止列表提醒，都需要在 Send 套餐之外额外订阅 Optimize。不要以为这些功能包含在 Foundation 或 Scale 套餐中——它们并不包含。
3. 域名发送密钥只能发送邮件，不能管理域名、路由或 Webhook。 如果你的应用需要创建路由、管理域名或配置 Webhook，就必须使用主 API 密钥。出于安全隔离考虑，域名发送密钥仅限用于 /messages 端点。使用域名发送密钥进行其他 API 调用会返回 401 错误。
4. 专用 IP 每个每月收费 59 美元，且需要预热——不要以为它们已包含在套餐中。 专用 IP 是 Scale 和 Enterprise 套餐可选的附加服务。新的专用 IP 初始没有信誉，必须逐步预热（先从较低发送量开始，并在 2-4 周内逐步增加）。在尚未预热的专用 IP 上发送大量邮件会导致投递率不佳。发送量较低时，Mailgun 的共享 IP 池通常能带来更好的效果。
5. 免费套餐每天限发 100 封邮件（不是每月），用于测试时限制很大。 对开发和测试工作流而言，这一限制比听起来严格得多。如果你需要在有实际意义的规模上测试批量发送、Webhook 处理或模板渲染，至少需要 Foundation 套餐（每月 35 美元，可发送 50,000 封）。每日限额在 UTC 午夜重置。

• 自我完善：如果你发现此处未涵盖的内容，请附上当天日期，将其添加到 references/learnings.md。

第 5 步 — 相关技能

• /sales-deliverability — 跨平台电子邮件投递率——SPF/DKIM/DMARC、预热、收件箱投递位置
• /sales-email-marketing — 跨工具的许可式电子邮件营销策略
• /sales-email-tracking — 电子邮件互动跟踪策略
• /sales-integration — 通过 Webhook/Zapier 将 Mailgun 连接到 CRM、Slack 或其他工具
• /sales-sendgrid — SendGrid 平台帮助——Mailgun 的主要竞争对手
• /sales-postmark — Postmark 平台帮助——Mailgun 的主要竞争对手
• /sales-customerio — Customer.io 平台帮助——使用类似 Mailgun 的事务性邮件 API
• /sales-do — 不确定该使用哪项技能？此路由器会根据任何销售目标匹配合适的技能。安装：npx skills add sales-skills/sales --skill sales-do

示例

示例 1：在 Node.js 应用中通过 REST API 发送事务性邮件

用户说：“我需要通过 Mailgun 从 Node.js 应用发送密码重置和订单确认邮件。” 技能会：

1. 指导用户创建 Mailgun 账户，并从控制面板复制 API 密钥
2. 逐步介绍如何添加并验证发送域名——添加 MX、SPF（include:mailgun.org）和 DKIM DNS 记录
3. 展示如何使用 mailgun.js SDK：使用 API 密钥和域名进行初始化，然后调用 mg.messages.create() 并传入 from、to、subject、html/text
4. 使用 Handlebars 变量创建两个域名级模板——一个用于密码重置（{{reset_url}}、{{expiry_minutes}}），另一个用于订单确认（{{order_number}}、{{items}}、{{total}}）
5. 建议在生产环境中创建域名发送密钥，将密钥的权限范围限制为仅用于发送
6. 设置 delivered、permanent_fail 和 complained 事件的 Webhook，以监控投递状况并触发警报 结果：用户拥有可用于生产环境的事务性邮件方案，包含模板、权限受限的 API 密钥、正确配置的 DNS 身份验证和投递监控

示例 2：为支持系统设置入站邮件路由

用户说：“我们希望在 [email protected] 接收客户回复邮件，并将其转发到我们的工单系统 Webhook。” 技能会：

1. 指导用户为 ourdomain.com 添加一条指向 Mailgun 入站服务器的 MX 记录
2. 在 Mailgun 界面中验证域名
3. 通过 API 创建路由：使用 match_recipient("[email protected]")，并配置 forward("https://app.ourdomain.com/api/tickets/inbound") 操作
4. 说明 Webhook 负载格式——发件人、主题、去除引用内容后的正文，以及作为文件上传的附件
5. 建议设置一个备用路由，使用 catch_all() 存储 3 天内未匹配的入站邮件（store(notify="https://app.ourdomain.com/api/catchall")），以免邮件被悄然丢弃
6. 展示如何使用正则表达式编写自定义解析规则，从主题行中提取工单 ID，并将邮件路由到现有工单 结果：用户拥有入站邮件路由，可将客户回复转发到工单系统，并通过兜底机制确保邮件不会遗漏

示例 3：使用 Mailgun Optimize 提高投递能力

用户说：“我们的 Mailgun 邮件被 Gmail 判定为垃圾邮件。该如何诊断并解决？” 技能会：

1. 检查用户是否已开通 Mailgun Optimize；如果没有，则建议使用每月 49 美元的 Pilot 套餐进行收件箱投递测试
2. 运行收件箱投递种子测试，确认邮件在 Gmail、Outlook、Yahoo 和其他服务商中的投递位置
3. 通过 Domains API 检查域名 DNS 身份验证，验证 SPF、DKIM 和 DMARC 记录是否正确配置
4. 在 Optimize 控制面板中检查发件人信誉，包括是否出现在黑名单中以及信誉评分
5. 通过批量上传 CSV 验证发送列表，移除无效、一次性和高风险地址（最多可将退信率降低 21%）
6. 检查 complained Webhook 事件，找出导致垃圾邮件投诉的内容或收件人 结果：用户可确定邮件被判定为垃圾邮件的根本原因（例如，缺少 DMARC、IP 被列入黑名单或退信率过高），并获得具体的修复方案和持续监控措施

故障排除

使用 Domain Sending Key 时邮件因 401 Unauthorized 被拒绝

症状：调用 GET /v3/domains 或 POST /v3/routes 等端点时，API 返回 401 Unauthorized，但发送邮件正常 原因：Domain Sending Key 仅限用于 /messages 端点。它不能用于管理域名、路由、Webhook、邮件列表或任何其他 Mailgun 资源。这是出于安全隔离而有意设置的限制。 解决方案：对于非发送操作，请使用主 API 密钥（可在 Mailgun 控制面板的 API Security 下找到）。Domain Sending Key 仅用于生产环境中的发送代码。如果需要以编程方式管理资源，请将主 API 密钥安全地存储在环境变量中，并在单独的服务或部署流水线中将其用于管理操作。

Webhook 事件未到达端点

症状：你在 Mailgun 中配置了 Webhook，但端点没有收到任何事件——服务器日志中也没有相关请求 原因：常见原因包括：（1）Webhook URL 无法公开访问（例如 localhost 或位于防火墙后），（2）端点返回非 2xx 状态码，导致 Mailgun 在重试后延长重试间隔，（3）Webhook 配置到了错误的域名，或（4）未生成相应事件（例如未启用打开/点击跟踪）。 解决方案：确认端点可公开访问——本地开发时可使用 ngrok 等工具。在 Mailgun 控制面板的 Sending > Webhooks 下查看投递状态和最近的尝试记录。确保端点能快速返回 200 状态码（几秒内）。确认 Webhook 配置到了正确的域名。对于打开/点击事件，请确认已在域名设置中启用跟踪。使用简单的端点（例如 webhook.site）进行测试，以确定问题出在 Mailgun 投递还是端点处理上。

邮件从美国区域发送，但域名位于欧盟区域（反之亦然）

症状：尝试发送邮件时，API 调用返回 404 或身份验证错误，尽管域名已验证且 API 密钥正确 原因：域名是在某个区域（美国或欧盟）创建的，但 API 调用使用了另一个区域的基础 URL。美国区域的域名必须使用 https://api.mailgun.net/v3/，欧盟区域的域名必须使用 https://api.eu.mailgun.net/v3/。域名创建后无法在区域之间迁移。 解决方案：在 Mailgun 控制面板中查看域名所属区域（在域名页面查找区域标识）。将 API 基础 URL 更新为与域名区域一致。如果需要切换区域（例如，为了符合 GDPR），必须删除域名并在正确的区域重新创建，然后重新验证 DNS 记录。更新所有应用程序配置、环境变量和 SDK 初始化设置，以使用正确的区域 URL。