发送邮件

Rovela 通过 API 发送邮件。控制台提供日志和监控视图，但实际发送是通过 API 调用完成的——可以来自你自己的代码，也可以来自控制台里的快速发送表单。

发送前的准备

发信前需要满足两个条件：

• 一个已验证的发信域名。from 地址必须属于你在「域名」里添加并验证过的域名。向未验证域名发送请求会被拒绝，返回一个点名该域名的 400。
• 一个 API 密钥。在「API 密钥」里创建；生产环境用 sending_access。

通过 API 发送

最少需要的字段是 from、to、subject，以及 html 或 text 之一：

curl -X POST https://api.rovela.dev/emails \
  -H "Authorization: Bearer re_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": "user@example.com",
    "subject": "你的账单",
    "html": "<p>感谢你的购买。</p>"
  }'

请求成功后返回邮件 id：

{"object": "email", "id": "9f1c2e40-..."}

to 字段接受单个地址字符串或最多 50 个地址的数组。cc 和 bcc 的写法相同。地址里的名字部分——上例中的 Acme——可以省略。

添加附件

附件用 base64 编码后内联在请求体里：

{
  "from": "billing@yourdomain.com",
  "to": "user@example.com",
  "subject": "你的账单",
  "html": "<p>请查收附件中的账单。</p>",
  "attachments": [
    {
      "filename": "invoice-2026-10.pdf",
      "content": "<base64 编码的内容>",
      "content_type": "application/pdf"
    }
  ]
}

定时发送

在请求里加上 scheduled_at 字段，填 ISO 8601 格式的时间戳，可以让邮件在指定时间才投递。时间戳必须至少比当前时间晚 5 分钟：

{
  "from": "newsletter@yourdomain.com",
  "to": "subscriber@example.com",
  "subject": "本周更新",
  "html": "...",
  "scheduled_at": "2026-11-01T09:00:00Z"
}

已排期的邮件在发送时间到达之前，可以用 PATCH /emails/:id 改时间或取消。一旦投递就无法撤回。

使用模板

如果你在「模板」里保存了模板，可以在发送时按 slug 引用，并传入变量值。使用模板时不需要 html 字段，正文来自模板：

{
  "from": "hello@yourdomain.com",
  "to": "user@example.com",
  "subject": "欢迎，{{first_name}}",
  "template": "welcome-email",
  "variables": {
    "first_name": "Alex",
    "plan": "Pro"
  }
}

查看投递状态

200 表示邮件已受理，不代表已到达。发送后查看状态的两种方式：

• GET /emails/:id——邮件当前的状态字段。
• GET /emails/:id/events——带时间戳的完整投递时间线。

生产环境建议用 webhook 代替轮询。控制台「邮件」页面的时间线视图不需要任何 API 调用。

抑制发送

向抑制列表里的地址发信，API 会正常受理并返回 id，但邮件实际上不会投递，状态变为 suppressed。如果某封预期能到的邮件没有出现，先查一下「抑制列表」页面。哪些情况会自动加入抑制列表，见 控制台总览。