API 参考文档

事务性邮件 REST API

该 API 接受经过认证的请求，校验项目范围（scope）与域名状态，检查抑制列表（suppression），随后将被接受的邮件加入队列。

2026-10-13下载 OpenAPI 3.1

身份认证

以 Bearer 令牌形式发送控制台签发的受限 srs_live_ 密钥。每个密钥有独立的 scope（emails:send、webhooks:write …）；已撤销或过期的密钥返回 401。

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[]`	是	收件人地址；to + cc + bcc 合计不超过 100 个。	`["user@example.net"]`
`subject`	`string`	是	邮件主题。	`您的订单已准备好`
`html`	`string`	否	HTML 正文。html 和 text 至少需要提供一个。	`<p>…</p>`
`text`	`string`	否	纯文本正文。text 和 html 至少需要提供一个。	`订单 #4821…`
`cc / bcc`	`string[]`	否	抄送和密送（计入 100 上限）。	`["team@example.com"]`
`reply_to`	`string[]`	否	最多 10 个回复地址。	`["support@example.com"]`
`send_at`	`string · date-time`	否	最多提前 30 天定时发送（RFC 3339）。	`2026-11-06T09:00:00Z`
`tags`	`object`	否	最多 20 个键值标签。	`{"type":"receipt"}`
`headers`	`object`	否	最多 8 个：In-Reply-To、References、List-Unsubscribe、List-Unsubscribe-Post。	`{"References":"<…>"}`
`template / variables`	`string / object`	否	已发布模板 ID；主题和正文由 variables 生成。	`"order-ready"`

响应代码

状态	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"
}

发送邮件

POST /v1/emails
Authorization: Bearer srs_live_…
Idempotency-Key: reset-4821
Content-Type: application/json

核心资源

POST/v1/emails将一封邮件加入队列

POST/v1/emails/batch单次请求最多 100 封邮件

GET/v1/emails列出最近的邮件

GET/v1/emails/{id}邮件状态

DELETE/v1/emails/{id}/schedule取消定时发送

GET/POST/v1/domains列出或添加发送域名

POST/v1/domains/{id}/verify运行 DNS 检查

POST/v1/suppressions将收件人加入抑制列表

GET/DELETE/v1/suppressions/{email}查询或移除抑制记录

GET/POST/v1/webhooks列出或创建 webhook 端点

DELETE/v1/webhooks/{id}删除端点

GET/v1/webhooks/{id}/deliveries投递尝试日志

POST/v1/webhooks/{id}/deliveries/{deliveryId}/replay重放一次投递

GET/POST/v1/templates列出或创建模板

响应模型

202 表示已进入队列，而非已送达收件箱。403 可能表示缺少 scope 或域名尚未验证。422 会阻止发送给已抑制的收件人。429 表示触发了速率限制。

当前服务限制

REST API 不支持附件。自定义标头仅允许 In-Reply-To、References、List-Unsubscribe 和 List-Unsubscribe-Post（最多 8 个）。托管邮箱独立运行：网页客户端支持最多 20 个附件、合计 25 MiB；已发布的桌面客户端发送上限为 10 MiB。HTTP 202 和 email.accepted 表示已接收处理；SMTP 接收不保证成功投递或进入收件箱。

当前访问模式

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

集成资源

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