API 参考文档

事务性邮件 REST API

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

下载 OpenAPI 3.1

身份认证

POST /v1/emails

请求 / 响应

请求cURL
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."
  }'
响应202 Accepted
HTTP/1.1 202 Accepted
Content-Type: application/json

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

输入参数

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

响应代码

状态HTTP说明
202Accepted邮件已进入队列；这并不表示已送达收件箱。
400Bad RequestJSON 无效或包含不支持的字段。
401UnauthorizedAPI 密钥无效、已过期或已撤销。
403Forbidden缺少 scope 或发件人域名尚未验证。
422Unprocessable Entity收件人位于抑制列表中。
429Too Many Requests已超出项目请求速率限制。
错误示例422 Unprocessable Entity
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将邮件加入队列
GET/v1/emails/{id}查询邮件状态
POST/v1/domains添加发送域名
POST/v1/domains/{id}/verify运行 DNS 检查
GET/POST/DELETE/v1/suppressions管理抑制列表中的收件人
GET/POST/DELETE/v1/webhooks管理事件端点

响应模型

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

当前访问模式

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

集成资源

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