认证
所有请求携带 Authorization 头。API Key 在控制台创建，明文仅显示一次。
curl https://api.nexorelay.com/v1/emails \
-H "Authorization: Bearer nxr_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ ... }'
在控制台获取 API Key →发送邮件
POST /v1/emails —— 同步校验发件域与参数，入队成功返回 202 与邮件 ID；后续状态经事件与 Webhook 回流。
POST https://api.nexorelay.com/v1/emails
{
"from": "Acme <
[email protected]>",
"to": ["
[email protected]"],
"subject": "Hello",
"html": "<strong>Hi</strong>",
"tags": { "order_id": "123" }
}
响应 202
{ "id": "email_abc123" }
模板发送
传 template_id 与 variables（与 subject/html/text 互斥），变量用 Handlebars 语法。
批量发送
POST /v1/emails/batch —— 单次最多 100 封，各自可不同内容。
POST https://api.nexorelay.com/v1/emails/batch
{ "emails": [ { "from": "...", "to": ["..."], "subject": "..." } ] }
→ 202 { "ids": ["email_1", "email_2", ...] }
查询邮件
GET https://api.nexorelay.com/v1/emails/email_abc123
→ 200 { "id": "email_abc123", "status": "DELIVERED", ... }
Webhook 事件
在控制台注册端点，事件以 HMAC 签名推送：email.sent / delivered / bounced / complained / opened / clicked。
POST https://api.acme.com/hooks/nexorelay
X-Nexorelay-Signature: sha256=...
{ "type": "email.delivered", "data": { "id": "email_abc123" } }
错误结构
统一错误结构 —— type 表明类别，code 是机器可读的具体原因。
{
"error": {
"type": "invalid_request_error",
"code": "domain_not_verified",
"message": "The sending domain \"mail.example.com\" is not verified."
}
}
幂等与限流
携带 Idempotency-Key 头（24h 内同 key 同 body 返回首次响应，不同 body 返回 409）；默认每 Key 10 req/s。
Idempotency-Key: order-8742