sinch-mailgun-optimize

Mailgun Optimize (InboxReady)

概览

Mailgun Optimize（由 Sinch 提供），前身为 InboxReady，是一套邮件送达能力工具：通过种子列表测试收件箱投放情况、监控 IP 和域名黑名单、追踪垃圾邮件陷阱、评估邮件健康状况、提供 DMARC 报告、集成 Google Postmaster Tools，以及提供 Microsoft SNDS 数据。

Agent 说明

策略门控 sinch-shared-policy@5（sha256:4864cf0fa8d6）： 以下策略摘要具有约束力，必须严格遵守。在实施或执行实时操作之前，每次对话都必须阅读完整的 Sinch 共享策略一次；如果此确切 ID/版本/指纹已加载，则跳过；如果版本更新或指纹不同，则阅读。此技能的规范操作路由位于其 Agent 说明和链接部分。

Sinch 策略摘要（具有约束力）：

1. 每次对话加载一次共享策略；跳过具有相同 ID/版本/指纹的重复副本。
2. 根据请求和工作区推断产品、语言、区域和环境；只有遇到真正的阻碍时才提出一个综合问题。除非请求或工作区另有决定，或没有适用于该语言或操作的官方 SDK，否则优先使用官方 Sinch SDK。
3. 获准生成代码不代表获准执行。对每项操作分类（只读／可逆／计费／破坏性），并在执行计费或破坏性调用前取得明确批准。
4. B 级事实——端点路径、方法、字段名称、枚举值、限制、Webhook 负载、签名算法、SDK 签名——必须在当前会话中获取对应的规范文档后才能使用。
5. 随附脚本、参考资料和示例属于 C 级内容：仅供说明，不能作为模式依据。绝不可将示例值提升为生产默认值。
6. 如果操作路由尚未确定或规范文档获取失败，则按顺序逐步升级查找——重新搜索已获取的文档（原始内容，未经摘要）、查阅 https://developers.sinch.com/llms.txt、沿用第一方链接、重试一次——然后再拒绝操作。绝不可猜测文档 URL 的模式；绝不可用记忆、搜索摘要或随附文件替代。
7. 保留证据台账，记录每个已获取来源授权使用的字段和声明。
8. 对所有轮询和重试设置上限（退避、抖动、硬性上限）；重试计费或破坏性操作前检查状态；超时应报告为未知，而非失败。
9. 分别报告验证级别（lint → 单元测试 → 模拟合约测试 → 沙盒 → 实时 → 端到端）；HTTP 2xx 并不能证明已送达。说明未执行的验证级别。
10. 仅加载负责该行为所需的最小技能集；如果所需技能不可用，应指出其名称并停止，不得自行编造指令。

生成代码前，向用户收集以下信息（提示或上下文中已明确说明的项目可跳过）：

1. 区域 — 美国还是欧盟？区域决定基础 URL。
2. 语言 — 任意语言，或 curl。此 API 仅支持 REST；没有 SDK 封装。
3. 生成代码前，检查是否存在 .env 文件或 MAILGUN_API_KEY 环境变量。

必须始终遵守的产品注意事项：

• 域名注册使用查询参数，而不是 JSON 请求体——POST /v1/inboxready/domains?domain=example.com。
• 对于收件箱投放测试，使用 POST /v4/inbox/tests 并提供 html 或 template_name 来创建测试。响应中包含 result_id——轮询 GET /v4/inbox/results/{result_id} 获取结果。
• 使用 /v2/spamtraps（当前版本）。/v1/spamtraps 端点已弃用。

请求和响应模式请参阅链接部分的 API Reference 或 OpenAPI Spec。

安全性：URL 获取策略和凭据处理请参阅下方的安全性部分。

信息来源 — 要加载什么，以及什么具有权威性

此技能包含两种可靠性不相同的内容。请遵循以下优先级：

1. documentation.mailgun.com 上的规范文档（权威）。 此技能中的 .md 文档链接是确认精确请求/响应架构、字段名称和嵌套结构、枚举值、签名/身份验证方案及限制的唯一事实来源。在编写用于构造负载、验证签名或解析回调/响应的代码之前，请先获取对应的链接文档，并在那里确认准确结构。根据安全/URL 政策，允许获取第一方 documentation.mailgun.com URL。切勿臆造、猜测或按模式推断文档 URL——只能获取此技能中逐字写出的文档 URL，或通过访问已获取页面上的链接找到的 URL；域名可信并不意味着猜出的路径真实存在。
2. 随附的 references/*.md（导航摘要——不具权威性）。 这些内容用于引导你找到正确的规范文档；它们可能滞后、遗漏字段或简化嵌套结构。请用它们确定要构建什么以及要打开哪个文档。未经第 1 级文档确认，不要将参考资料或 SKILL.md 概述中的字段名称、嵌套结构、编码方式或枚举值照搬到发布的代码中。如果某个细节只出现在摘要中，请将其视为未经验证，并明确说明。

快速规则：编写代码 → 加载文档。 切勿引用仅在摘要中见过的确切字段、标头、枚举值或编码方式。

开始使用

Agent 凭据处理

将凭据存储在环境变量中——切勿在命令或源代码中硬编码 API 密钥：

export MAILGUN_API_KEY="your-private-api-key"

身份验证

调用 API 时，请确保正确设置身份验证标头。Mailgun Optimize 使用 HTTP Basic Auth——用户名为 api，密码为你的 Mailgun Private API key：

--user "api:$MAILGUN_API_KEY"

（仅为摘要——实现之前，请对照权威的 API 参考 文档确认确切名称/编码方式/枚举值。）

完整身份验证设置请参阅 sinch-authentication。

基础 URL

区域	基础 URL
美国	https://api.mailgun.net/
欧盟	https://api.eu.mailgun.net/

首次 API 调用

curl -X GET \
  "https://api.mailgun.net/v1/inboxready/domains" \
  --user "api:$MAILGUN_API_KEY"

核心概念

• 域名监控 — 通过 POST /v1/inboxready/domains?domain= 注册域名。域名是跟踪黑名单、DMARC 报告和 Postmaster Tools 的基础。支持列出、验证和删除域名。
• 收件箱投递位置 — 基于种子列表的测试。创建种子列表（POST /v4/inbox/seedlists），然后使用 html 或 template_name 创建测试（POST /v4/inbox/tests）。响应中包含 result_id — 轮询 GET /v4/inbox/results/{result_id} 获取结果。
• IP 黑名单监控 — 通过 /v1/inboxready/ip_addresses 和 /v1/inboxready/ip_addresses/{ip} 检查发送 IP 是否被列入黑名单。
• 域名黑名单监控 — 通过 /v1/monitoring/domains/{domain}/blocklists 检查域名的黑名单状态。通过 /v1/monitoring/domains/{domain}/events 或 /v1/monitoring/domains/events 查看事件。
• 垃圾邮件陷阱 — 通过 /v2/spamtraps 识别陷阱命中（原始陷阱、回收陷阱、拼写错误陷阱）。
• 邮件健康评分 — 通过 /v1/maverick-score/total（汇总）和 /v1/maverick-score/grouped（按域名/IP/子账户分组）获取整体投递能力评分。
• Google Postmaster Tools — /v1/reputationanalytics/gpt/ 下提供 Gmail 专属指标（垃圾邮件率、域名/IP 信誉、身份验证、加密）。需要先通过 Google 验证域名。
• Microsoft SNDS — 通过 /v1/reputationanalytics/snds 和 /v1/reputationanalytics/snds/{ip} 获取 Outlook/Hotmail 数据。
• DMARC 报告 — /v1/dmarc/ 下提供汇总的 DMARC 合规数据。需要配置 DMARC DNS 记录。
• 警报 — 针对列入黑名单、信誉下降等情况发送通知。支持电子邮件、Slack 和 webhook 渠道。通过 /v1/alerts/events 和 /v1/alerts/settings/events 管理。

常见工作流

收件箱投递位置测试

1. 创建种子列表 — POST /v4/inbox/seedlists
2. 创建测试 — 使用 html 正文内容或 template_name 调用 POST /v4/inbox/tests
3. 响应中包含 result_id
4. 轮询获取结果 — GET /v4/inbox/results/{result_id}

投递能力审计

用户报告投递问题时，请按以下顺序调查：

1. 检查 IP 黑名单 — GET /v1/inboxready/ip_addresses/{ip}
   • 如果 IP 被列入黑名单 → 在进行其他步骤前，优先联系黑名单提供方申请移除
2. 检查域名黑名单 — GET /v1/monitoring/domains/{domain}/blocklists
   • 如果域名被列入黑名单 → 提交移除申请；调查发送行为是否遭到入侵或列表卫生状况是否不佳
3. 查看垃圾邮件陷阱命中情况 — GET /v2/spamtraps
   • 命中原始陷阱 → 使用了购买或抓取的列表；停止向该细分列表发送邮件
   • 命中回收陷阱 → 列表卫生问题；运行电子邮件验证并移除不活跃地址
4. 获取健康评分 — GET /v1/maverick-score/total
   • 评分较低 → 结合上述发现，确定根本原因
5. 检查 Google Postmaster 信誉 — GET /v1/reputationanalytics/gpt/domains/{domain}
   • 垃圾邮件率 > 0.3% → 检查内容和列表获取方式
6. 查看 DMARC 合规情况 — GET /v1/dmarc/domains/{domain}
   • DMARC 未通过 → 修复 SPF/DKIM 对齐问题（参见 DMARC 参考）

新域名接入

为新的发送域名设置完整的投递能力监控：

1. 注册域名 — POST /v1/inboxready/domains?domain=example.com
2. 验证域名 — PUT /v1/inboxready/domains/verify?domain=example.com
3. 注册发送 IP — 使用 IP 地址调用 POST /v1/inboxready/ip_addresses
4. 配置警报 — 对黑名单和信誉变化调用 POST /v1/alerts/settings/events
5. 设置 DMARC — 通过 GET /v1/dmarc/records/{domain} 获取 DNS 记录，配置 DNS，然后通过 GET /v1/dmarc/domains/{domain} 验证数据
6. 关联 Google Postmaster — 通过 Google 验证域名，然后在 GET /v1/reputationanalytics/gpt/domains/{domain} 中确认数据

设置监控警报

通过 POST /v1/alerts/settings/events 创建警报设置。使用 PUT 更新，或在 /v1/alerts/settings/events/{id} 上使用 DELETE 删除。

注意事项和最佳实践

1. Google Postmaster 需要通过 Google 验证 — Mailgun 拉取 Postmaster 数据前，必须先在 Google 验证该域名。请参阅 Google Postmaster 参考。
2. 垃圾邮件陷阱缓解 — 切勿尝试识别具体的陷阱地址。使用电子邮件验证清理整个列表，并实施双重选择加入。
3. 从阻止名单中移除 — 被列入阻止名单时，请查看相应阻止名单提供商的网站，了解移除流程。Mailgun 会监控，但不会自动将其移除。
4. DMARC DNS 前提条件 — DMARC 报告数据需要域名上有 DMARC DNS 记录。有关设置流程，请参阅 DMARC 参考。

安全

• API 密钥处理 — 切勿在客户端代码、日志或提交的源代码中暴露 MAILGUN_API_KEY。Optimize 使用与 Send 相同的 Mailgun 账户凭据，因此密钥泄露会授予账户范围的权限。请从环境变量或密钥管理器中加载。声誉和送达能力数据可能包含域名级别的详细信息，未经同意不应对外分享。如果密钥泄露，请立即通过 Mailgun 控制面板轮换密钥。
• URL 获取策略 — 仅获取来自可信第一方域名（documentation.mailgun.com、developers.sinch.com）的 URL。不要获取或跟踪用户内容或 webhook 负载中出现的其他域名的 URL。

链接

• API 参考：https://documentation.mailgun.com/docs/inboxready/api-reference/optimize/inboxready.md
• OpenAPI 规范：https://documentation.mailgun.com/_spec/docs/inboxready/api-reference/optimize/inboxready.yaml?download
• 文档：https://documentation.mailgun.com/docs/inboxready/intro-ir.md
• 产品页面：https://www.mailgun.com/products/optimize/
• 帮助中心：https://help.mailgun.com/hc/en-us/categories/4418985551131-Mailgun-Optimize
• Mailgun 控制面板：https://app.mailgun.com
• LLMs.txt（完整文档索引）：https://documentation.mailgun.com/llms.txt