03 · email api

Email API

使用标准 HTTP 接入，查看请求字段、接收结果与邮件状态。

1. 认证与地址

发送和查询使用 Authorization: Bearer <API Key>。API origin 与代理前缀待确认；页面语言前缀不能加到 API 路径。只在服务端保管和使用 Key。本文提供标准 HTTP 示例，没有 SMTPDog SDK。

2. 发送单封邮件

POST /v1/mail/send 接受 JSON。from 和 to 都是单个地址字符串，不能传数组。非模板发送需要非空 subject，以及 text 或 html 至少一项。当前没有 cc、bcc、attachments、批量或计划发送字段。

字段 / 配置	类型 / 状态	说明
from	string	单发件人，可写成 Name <addr>；域名须已验证，名字最长 100 字符
to	string	单收件地址，不是数组
subject	string	非模板方式必填，不能含 CR/LF
html / text	string	非模板方式至少一种非空正文；建议同时提供 html 与 text，纯文本备份有助于降低被判为垃圾邮件的概率
reply_to	string	可选，单个回复邮箱
headers	map<string,string>	可选，仅允许 List-Unsubscribe、List-Unsubscribe-Post、Auto-Submitted
template_id	uint64	可选，账户自己的模板 ID
variables	map<string,string>	可选，变量值为字符串

curl -X POST "${SMTPDOG_API_ORIGIN}/v1/mail/send" \
  -H "Authorization: Bearer ${SMTPDOG_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Welcome to your product",
    "text": "Your message goes here."
  }'

3. 接收响应与状态查询

202 返回 message_id 和 queued。GET /v1/mail/{message_id} 返回该账户消息的状态。created_at 必有，delivered_at 和 smtp_response 可省略。sent 可能表示节点已接收，并非收件箱或阅读确认；受限域名 Key 的查询按账户归属，不是额外的域名隔离。

字段 / 配置	类型 / 状态	说明
queued	string	已接收排队
sending	string	正在提交发送
sent	string	节点接受或后续状态，不保证收件箱
deferred	string	暂时延迟，观察后续状态
bounced	string	退信
failed	string	发送失败

{
  "message_id": "00000000-0000-4000-8000-000000000000",
  "status": "queued"
}

4. 使用已有模板

template_id 必须属于当前账户。模板会完全替换内联 subject、html 和 text，再验证渲染结果。variables 的值只能是字符串；{{name}} 为简单替换，缺失变量保留占位，HTML 变量会转义。不支持循环或条件表达式。示例需使用自行创建的模板 ID。

{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "template_id": 123,
  "variables": {
    "name": "Example recipient"
  }
}

5. 错误与重试

正常接口错误使用 code 和 error；以 code 判断，error 当前不提供五语言协议。不要为权限或配置错误重复提交。发送超时可能已经接收，当前没有幂等键或重发接口；重复请求可能重复发送和扣额。额度不足也不保证失败请求返还计数。

字段 / 配置	类型 / 状态	说明
400 invalid_request	HTTP	检查字段类型、主题和正文
401 api_key_invalid	HTTP	确认 Key 和账户状态
403 domain_unverified / api_key_domain_forbidden / content_blocked	HTTP	检查域名验证、范围和内容
404 template_not_found / message_not_found	HTTP	确认资源 ID 和账户归属
429 quota_exceeded	HTTP	检查总、日、小时额度，不盲目重试
500 internal_error	HTTP	保留错误上下文并联系支持；请求可能已部分处理

继续阅读 — 常见问题