为 AI 代理接入邮件发送功能
面向需要为他人项目添加事务性邮件功能的编码代理（coding agent）和助手的机器可读指引——应调用什么、按什么顺序调用，以及每次发送前应运行哪些检查。
下载 OpenAPI 3.1在编写任何代码之前
- 向用户索取项目 API 密钥，或请他们在 https://app.srs-postline.com/zh/login 创建一个沙箱密钥——切勿凭空捏造、猜测密钥，也不要复用其他项目的密钥。
- 将密钥存放在服务端环境变量中。不要将其放入前端代码、移动应用包、公开仓库或已提交的 .env 文件中。
- 在生成请求代码之前先阅读 /llms.txt 和 openapi/postline.yaml；不要凭猜测使用字段名或端点。
最小化发送示例
POST /v1/emails
Authorization: Bearer srs_live_...
Idempotency-Key: <stable-id-per-logical-send>
Content-Type: application/json
{
"from": "Sender Name <info@example.com>",
"to": ["user@example.net"],
"subject": "主题",
"html": "<p>正文</p>",
"text": "正文"
}每次发送前应运行的检查
- 始终发送一个从触发动作（订单 ID、事件 ID）派生出的 Idempotency-Key，以避免重试导致重复发送。
- 切勿将 OTP 验证码、密码重置令牌或其他机密信息放入会被记录日志或转发到邮件正文之外的字段中。
- 为任务申请所需的最小 API 密钥权限范围（发送邮件只需 emails:send 即可；除非任务确有需要，否则不要申请 domains:write 或 api_keys:write）。
- 每次调用的收件人数量上限为 100。当前 API 不接受附件或自定义标头；应拒绝文件或提供链接，不要声称文件已作为附件发送。
- 不要在收到 4xx 响应时静默重试。只有 429 和 503 可以安全重试，且必须采用退避（backoff）策略。
处理每一种响应状态码
- 202——已加入队列，尚未送达。如果之后需要查询状态，请保存返回的 id。
- 400——请求负载无效；请修正请求内容，不要原样重试。
- 401——密钥无效或已过期；应停止操作并告知用户，不要臆造新密钥。
- 403——缺少所需权限范围，或发送域名尚未通过验证；请告知用户先完成域名验证再继续。
- 422——收件人处于抑制列表中（曾发生退信/投诉）；不要再向该收件人重试发送。
- 429——已触发速率限制；应退避后稍后重试，不要密集循环重试。
- 503——队列不可用；应采用退避策略重试，不要转而使用非官方的发送方式。
如果任务包含接收事件
仅通过 HTTPS 注册 webhook 端点。在信任任何负载之前，务必自行重新计算签名；不要因为某个请求“看起来像内部请求”就跳过验证。
signature = HMAC-SHA256(webhook_secret, timestamp + "\0" + event_id + "\0" + raw_body)
与 Postline-Signature 请求头比对（constant-time compare）
如果 Postline-Timestamp 超出允许窗口则拒绝
保存 event_id 并确保每个事件只处理一次机器可读参考资料
- /llms.txt——为代理上下文窗口精简整理的规则索引。
- /openapi/postline.yaml——每个端点的完整 OpenAPI 3.1 架构定义。
- /zh/api/——面向人类阅读的 API 参考文档。
- /zh/webhooks/——webhook 签名与重试机制详情。
当前访问模式
当前密钥使用 srs_live_。验证客户 From 域之前，共享 sandbox 发件人只能发送给项目成员。验证后仍受套餐配额、抑制列表、收件人限流和滥用控制约束。202 表示已排队，而非已送达。
集成资源
人类和 AI 代理可使用分步指南；字段级事实以 OpenAPI 为准。