使用 MCP 连接 AI 代理

它是什么

Postline 托管 MCP 服务器位于 https://api.srs-postline.com/mcp，提供邮件、域名、抑制列表和 Webhook 的类型化工具。

在编写任何代码之前

• 向用户索取项目 API 密钥，或请他们在 https://app.srs-postline.com/zh/login 创建一个沙箱密钥——切勿凭空捏造、猜测密钥，也不要复用其他项目的密钥。
• 将密钥存放在服务端环境变量中。不要将其放入前端代码、移动应用包、公开仓库或已提交的 .env 文件中。
• 先在沙箱项目中使用 srs_test_ 密钥。沙箱只能发送给用户已验证的收件人，因此真正的收件箱投递需要经过审核的正式（live）项目——在审核完成之前，不要承诺正式发送功能可用。
• 在生成请求代码之前先阅读 /llms.txt 和 openapi/postline.yaml；不要凭猜测使用字段名或端点。

连接方式

使用 Postline Bearer 密钥连接托管端点，无需下载或本地构建。

claude mcp add --scope user --transport http postline \
  https://api.srs-postline.com/mcp \
  --header "Authorization: Bearer srs_live_xxx"

export POSTLINE_API_KEY='srs_live_xxx'
codex mcp add postline --url https://api.srs-postline.com/mcp \
  --bearer-token-env-var POSTLINE_API_KEY

每次发送前应运行的检查

• 始终发送一个从触发动作（订单 ID、事件 ID）派生出的 Idempotency-Key，以避免重试导致重复发送。
• 切勿将 OTP 验证码、密码重置令牌或其他机密信息放入会被记录日志或转发到邮件正文之外的字段中。
• 为任务申请所需的最小 API 密钥权限范围（发送邮件只需 emails:send 即可；除非任务确有需要，否则不要申请 domains:write 或 api_keys:write）。
• 每次调用的收件人数量上限为 100。当前 API 不接受附件或自定义标头；应拒绝文件或提供链接，不要声称文件已作为附件发送。
• 不要在收到 4xx 响应时静默重试。只有 429 和 503 可以安全重试，且必须采用退避（backoff）策略。

处理每一种响应状态码

• 202——已加入队列，尚未送达。如果之后需要查询状态，请保存返回的 id。
• 400——请求负载无效；请修正请求内容，不要原样重试。
• 401——密钥无效或已过期；应停止操作并告知用户，不要臆造新密钥。
• 403——缺少所需权限范围，或发送域名尚未通过验证；请告知用户先完成域名验证再继续。
• 409——幂等性冲突；应将其视为原始请求已经发送成功。
• 422——收件人处于抑制列表中（曾发生退信/投诉）；不要再向该收件人重试发送。
• 429——已触发速率限制；应退避后稍后重试，不要密集循环重试。
• 503——队列不可用；应采用退避策略重试，不要转而使用非官方的发送方式。

机器可读参考资料

• /llms.txt——为代理上下文窗口精简整理的规则索引。
• /openapi/postline.yaml——每个端点的完整 OpenAPI 3.1 架构定义。
• /zh/api/——面向人类阅读的 API 参考文档。
• /zh/webhooks/——webhook 签名与重试机制详情。