通过 API 和 MCP 管理邮件送达率与退信

TrekMail 控制面板会在每个域名的统计选项卡中显示两类退信数据：

1. **30 天汇总：**已发送、已送达、软退信和硬退信的数量，以及送达率和退信率。
2. **按收件人列出的清单：**最近 50 封出站退信及接收服务器的 SMTP 状态码和响应，帮助你了解特定邮件失败的原因。

现在可以通过 REST API 和 MCP 服务器获取这两类数据。代理无需打开控制面板，即可提取退信原因、汇总信誉状况，并将数据用于邮件列表清理工作流。

可用数据

这三项操作都需要 domains:read（限定邮箱的列表则可使用 mailboxes:read）。它们都是只读操作，无需幂等键。

API 使用与控制面板统计卡片相同的送达率数据，因此两个视图始终保持一致。

REST API：快速示例

域名汇总

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status 与控制面板显示的三种状态信号相同：

• **good：**退信率低于 2%。
• **warning：**退信率介于 2% 和 5% 之间。
• **poor：**退信率达到或超过 5%。请检查并清理发送列表。

forwarding_bounces_excluded 表示在计算比率时排除了多少次与转发相关的退信（与控制面板一致，后者将这些退信视为路由问题，而不是发件人列表问题）。

按收件人列出的退信清单

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

查询参数

限定邮箱的列表

如需按发件人分析信誉问题，请将范围限定到一个邮箱：

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

响应结构与域名端点相同。

SMTP 响应的隐私保护

TrekMail 会在返回 SMTP 响应之前删除内部诊断信息。保留的消息与控制面板中向账户所有者显示的内容相同，旨在帮助诊断送达问题，而不会暴露服务器内部信息。

MCP 工具

这三个工具接受与 REST 端点相同的参数。它们都是只读工具，不会更改邮件或账户设置。

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

大批量发件人的送达率标头

如果你发送营销邮件或订阅式批量邮件，主要邮箱提供商可能会要求使用一键退订标头。Google 将此规则应用于超过大批量发件人门槛的发件人所发送的营销和订阅消息；一键退订规则不适用于事务性消息。添加这些标头有两种方式：

按邮件设置（精细控制）。 通过 headers 字段将标头传入 POST /api/v1/messages/send：

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

headers 字段仅接受少量白名单值：List-Unsubscribe、List-Unsubscribe-Post、Reply-To，以及任何 X-* 自定义跟踪标头。标头注入（CR/LF）和托管标头（From、Subject、Date、Message-Id、Authentication-Results、DKIM-Signature 等）会以 422 拒绝。

整个账户统一设置（只需设置一次）。 如果此账户的每封出站邮件都由自动化流程发送，可以为账户启用 auto_list_unsubscribe。启用后，平台会为每封尚未包含该标头的出站邮件添加仅含 mailto 地址的 List-Unsubscribe 标头。系统不会添加 List-Unsubscribe-Post，因此这一备用方案不符合 RFC 8058 的一键退订要求。若要提供符合服务商要求的一键退订，请像上面的示例一样，在每封邮件中同时提供两个标头，并使用你自己的 HTTPS 退订端点。调用方提供的标头始终优先。此开关默认为关闭，现有账户不会受到影响。

对于一对一的个人邮件，请保持开关关闭。如果存在此标头，Gmail 可能会在发件人旁边显示退订按钮，这通常不适合个人对话。

AI 代理的使用模式

这些端点可支持多种高价值工作流：

• 每周信誉摘要。 每周一为账户中的每个域名调用 get_domain_deliverability，并将摘要发布到 Slack 或 Teams。只显示 status 为 warning 或 poor 的域名。
• 基于退信的列表清理。 调用 list_domain_bounces?type=hard&days=14，对 recipient_email 去重，然后从发送列表中排除这些地址。硬退信通常表示收件人地址已不存在，重新发送会浪费你的送达率资源。
• 按发件人分析。 当单个邮箱的 bounce_rate 突然上升时，对其调用 list_mailbox_bounces，并按 smtp_status_code 分组。550 状态码激增可能意味着地址列表已经过时；421 状态码激增可能意味着接收邮件服务器限制了你的发送速率。
• 客户支持调查。 当用户报告邮件未送达时，让代理调用 list_domain_bounces?recipient=<their-address>。SMTP 响应可能会提示下一步操作，例如清理已满的收件人邮箱、解除收件人一侧的拦截或修复 DMARC 拒收问题。

版本管理

这些端点遵循与 v1 API 其余部分相同的版本约定：只进行增量添加，不会在没有 v2/ 命名空间的情况下进行破坏性字段重命名。

相关内容

• 垃圾邮件指标：入站垃圾邮件防护遥测数据（get_spam_metrics、get_spam_summary）。
• 电子邮件验证器：发送前清理列表，从源头防止退信。
• API 概览：身份验证、权限范围、速率限制和幂等性。