文档

安全启用 Postline

域名验证、API 访问、沙箱发送、抑制列表（suppression）与投递事件。

2026年7月24日更新打开 API 参考文档

生产环境检查清单

验证 From 域名的所有权。
发布提供的 DKIM 记录，并通过 SPF 授权回信路径（return-path）基础设施。
配置 DMARC alignment，并在启用生产发送前检查结果。
在沙箱环境使用受限范围的测试密钥，在生产环境使用单独的正式密钥。
以幂等方式处理退信（bounce）和投诉（complaint）webhook，并遵循抑制（suppression）决策。

POST /v1/emails

请求 / 响应

curl --request POST 'https://api.srs-postline.com/v1/emails' \
  --header 'Authorization: Bearer srs_live_...' \
  --header 'Idempotency-Key: order_4821' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "Postline <info@example.com>",
    "to": ["user@example.net"],
    "subject": "Your order is ready",
    "html": "<p>Order #4821 is ready.</p>",
    "text": "Order #4821 is ready."
  }'

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id": "msg_01JPOSTLINEEXAMPLE",
  "status": "queued",
  "created_at": "2026-08-22T12:00:00Z"
}

输入参数

参数	类型	必填	说明	示例
`Authorization`	`header · string`	是	以 Bearer 令牌形式传递控制台签发的受限 API 密钥。	`Bearer srs_live_…`
`Idempotency-Key`	`header · string`	否	一次逻辑发送的稳定标识符；强烈建议提供。	`order_4821`
`from`	`string`	是	已验证域名上的发件人名称和地址。	`Postline <info@example.com>`
`to`	`string[]`	是	一至 100 个收件人邮箱地址。	`["user@example.net"]`
`subject`	`string`	是	邮件主题。	`您的订单已准备好`
`html`	`string`	否	HTML 正文。html 和 text 至少需要提供一个。	`<p>…</p>`
`text`	`string`	否	纯文本正文。text 和 html 至少需要提供一个。	`订单 #4821…`

响应代码

状态	HTTP	说明
`202`	Accepted	邮件已进入队列；这并不表示已送达收件箱。
`400`	Bad Request	JSON 无效或包含不支持的字段。
`401`	Unauthorized	API 密钥无效、已过期或已撤销。
`403`	Forbidden	缺少 scope 或发件人域名尚未验证。
`422`	Unprocessable Entity	收件人位于抑制列表中。
`429`	Too Many Requests	已超出项目请求速率限制。

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "recipient suppressed"
}

认证相关术语

Postline 对邮件进行 DKIM 签名。SPF 是在 DNS 中发布的授权策略。DMARC 用于评估可见的 From 域名与经过认证的 SPF 或 DKIM 身份之间的 alignment；SPF 和 DMARC 并不作为邮件签名使用。

TLS 保护受支持节点之间传输中的数据。普通邮件并非端到端加密，收件方服务商可以处理邮件内容。

投递结果

收件服务器接受一封邮件并不能证明该邮件已进入收件箱。已接受（accepted）、延迟（deferred）、硬退信（hard bounce）、软退信（soft bounce）、投诉（complaint）、已抑制（suppressed）、进入垃圾邮件（spam placement）和进入收件箱（inbox placement）应被视为不同的结果。

当前访问模式

当前密钥使用 srs_live_。验证客户 From 域之前，共享 sandbox 发件人只能发送给项目成员。验证后仍受套餐配额、抑制列表、收件人限流和滥用控制约束。202 表示已排队，而非已送达。

集成资源

人类和 AI 代理可使用分步指南；字段级事实以 OpenAPI 为准。