Amail

Appearance

HTTP API ​

认证：

http
Authorization: Bearer am_xxxxxxxxxxxx

风格对齐 Resend Email API。发件邮箱由通道「发件人覆盖」决定，不必传真实 From 地址。

发送 ​

http
POST /emails
json
{
  "to": ["[email protected]"],
  "subject": "你好",
  "html": "<p>测试邮件</p>"
}

必须提供 html 或 text 之一。to 可为字符串或数组（最多 50）。

可选字段：

字段说明
from显示名，或 名字 <任意邮箱>。邮箱会被改成通道发件地址。
provider_id发件通道。省略或 auto 时由服务器选择。兼容旧字段 provider。
cc / bcc / reply_to抄送、密送、回复地址
headers / tags / attachments自定义头、标签、附件
scheduled_at定时发送：ISO 8601 或 in 5 minutes

请求头 Idempotency-Key 可用来去重。成功响应：{ "id": "..." }。SMTP 失败时仍返回 id，用查询接口看 last_event。

批量发送 ​

http
POST /emails/batch

一次最多 100 封。不支持 attachments。

json
[
  { "to": "[email protected]", "subject": "你好 1", "text": "测试 1" },
  { "to": "[email protected]", "subject": "你好 2", "text": "测试 2" }
]

请求头 x-batch-validation：

  • strict（默认）：任一封校验失败则整批不发，返回 422
  • permissive：能发的照发；响应带 errors: [{ index, message }]

成功：

json
{
  "data": [{ "id": "..." }, { "id": "..." }]
}

查询 ​

http
GET /emails/:id
json
{
  "object": "email",
  "id": "...",
  "from": "通知 <[email protected]>",
  "to": ["[email protected]"],
  "subject": "你好",
  "html": "<p>…</p>",
  "text": "…",
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "last_event": "delivered",
  "status": "delivered",
  "scheduled_at": null,
  "created_at": "2026-09-13T04:00:00.000Z",
  "sent_at": "2026-09-13T04:00:01.000Z"
}

last_event 大致对应 delivered / failed / queued / scheduled / sent / canceled。

邮件列表 ​

http
GET /emails?limit=20&after=email_id
json
{
  "object": "list",
  "has_more": false,
  "data": []
}

limit 默认 20，最大 100。after / before 为游标，不能同时用。列表项不含正文。

改期 ​

仅定时邮件：

http
PATCH /emails/:id
Content-Type: application/json

{ "scheduled_at": "2026-08-05T11:52:01.858Z" }

成功：{ "object": "email", "id": "..." }。

取消 ​

仅 queued 或 scheduled：

http
POST /emails/:id/cancel
DELETE /emails/:id

成功：{ "object": "email", "id": "...", "deleted": true }。

SMTP 列表 ​

http
GET /emails/providers
json
{
  "data": [
    {
      "id": "smtp_xxx",
      "name": "通知邮箱",
      "host": "smtp.example.com",
      "from_address": "[email protected]",
      "from_name": "通知中心"
    }
  ]
}

错误 ​

json
{
  "statusCode": 422,
  "name": "validation_error",
  "message": "Either html or text is required"
}