事务邮件 API（2026）：是什么，以及如何用 Rovela 发送

什么是事务邮件 API、覆盖哪些信件，以及如何用 Rovela 发送：POST /emails、已验证域名、Idempotency-Key 与投递追踪。

什么是事务邮件 API

事务邮件 API 是产品把「用户刚刚触发的那封信」发出去的方式——注册验证码、密码重置、订单收据、安全告警——通常就是一次普通的 HTTP 请求。每封信打给明确的收件人，内容是对方请求或触发的信息，这和向名单群发的通讯不是一类问题。Rovela 的事务邮件产品围绕这个模式：你向 /emails POST JSON，Rovela 负责入队、用你域名的密钥做 DKIM 签名、完成 SPF 对齐，并返回 message id，方便你追踪后续状态。

这篇是事务邮件 API 的「是什么、怎么用」，以 Rovela 为具体产品。它不是事务邮件与营销邮件（那篇讲品类划分），也不是AI 应用的事务邮件（AI 应用场景），更不是5 分钟发送第一封邮件那种五分钟上手。若还在选传输方式，先看Email API 与 SMTP 对比；若已经决定走 HTTPS，继续往下即可。

可以从Email API产品页、快速开始、发送邮件 API和身份认证入手。

本系列相关产品指南：

为什么产品用 API，而不是自己跑邮件服务器

事务邮件必须正确、及时、可追踪。重置密码的信没到，或到了两封、链接还不一致，就是一单客服。API 的好处是：

应用已经会 HTTP。 服务端 POST、Authorization: Bearer 加 JSON，和其余后端一样。Rovela 没有官方 SDK 要装——API 就是 https://api.rovela.dev 上的纯 HTTP 与 JSON（安装说明）。
受理是同步的，投递不是。 返回 200 和 {"object":"email","id":"…"} 表示 Rovela 已接受并入队，不等于已经进收件箱（快速开始）。之后可以GET /emails/:id，或订阅投递 webhook。
重试可以做成安全的。 Idempotency-Key 请求头（最长 256 字符）让 24 小时内的相同重试返回原响应，而不会再发一封（邮件 API 的幂等键）。
域名是你自己的。 from 必须在已验证的发信域名上，未验证会被 400 拒绝。见已验证域名的 Email API和什么是邮箱域名？。

发送字段

发送邮件 API接受：

字段	必填	说明
`from`	是	如 `"Acme <hello@yourdomain.com>"`，且域名已验证
`to`	是	一个地址或数组。`to` + `cc` + `bcc` 合计不超过 50 人
`subject`	是*	模板自带主题时可省略
`html` / `text`	与 `template` 三选一	能同时给 HTML 和 text 就同时给
`template`	否	`{ id, variables }`，与 `html`/`text` 互斥
`cc` / `bcc`	否	计入 50 人上限，也计入额度
`reply_to`	否	回信地址
`scheduled_at`	否	将来的 ISO 8601 时间（务必带时区偏移）
`tags`	否	随消息返回的标签
`headers`	否	自定义头
`topic_id`	否	只发给订阅了该主题的联系人
`attachments`	否	`{ filename, content（base64）, content_type }`

额度按收件人计，不是按封数：to/cc/bcc 里三个人就扣三次月额度。一批 100 封、每封两个收件人，计 200。

发送第一封事务邮件

前置：账号、已验证发信域名、形如 re_… 的 API Key。生产发信优先 sending_access——只能发信。读信、改期、取消需要 full_access 或 Dashboard session（身份认证）。没有另一套「沙箱 Key」；免费计划的 Key 发的就是真信（快速开始，定价）。

curl -X POST https://api.rovela.dev/emails \
  -H "Authorization: Bearer re_your_sending_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verify-signup-8f3a2c" \
  -d '{
    "from": "Acme <no-reply@yourdomain.com>",
    "to": "alice@example.com",
    "subject": "Your Acme code: 482913",
    "html": "<p>Your verification code is</p><p style=\"font-size:28px;letter-spacing:6px\"><b>482913</b></p><p>It expires in 10 minutes.</p>",
    "text": "Your verification code is 482913. It expires in 10 minutes."
  }'

Idempotency-Key 让超时重试保持安全：读者只收到一个验证码，不会收到两个对不上的码。生成、哈希、校验的完整做法见验证码示例和用邮件 API 发送验证码。

应用里同样是一次 fetch 或 urllib 调用，见从应用发送事务邮件和HTTP 邮件 API。若要按 curl 把请求头、错误、批量与取消走一遍，见用 curl 发送邮件。

几乎每个产品都会发的几类信

注册 / 登录验证码和魔术链接 — 在服务端生成秘密，同时发 HTML + text，按「这一次尝试」设置幂等键。见验证码示例、用邮件 API 发送验证码。
密码重置 — 来自你域名的一次性、短时效链接。密码重置示例、安全的密码重置邮件。
欢迎邮件 — 常用已存储模板，文案不必随发版改。欢迎邮件模板示例、用模板发送欢迎邮件、邮件模板 API 指南。
发票和收据 — 在同一次 POST 里附上 PDF。发票附件示例、发送带 PDF 附件的发票邮件。
提醒与回访 — 批量（最多 100 封）或 scheduled_at。见批量事务邮件 API和定时发送邮件。

要把这些打包进同一个 SaaS，可看SaaS 应用的 Email API。运维告警类通知见邮件通知 API。

`200` 之后：状态、事件和 webhook

GET /emails/:id（以及 GET /emails/:id/events）需要 full_access 或 session。生产环境请订阅 webhook，而不是轮询：Webhook 概览、事务邮件 Webhook。通常需要你侧改状态的是 email.bounced、email.complained，以及（面向联系人/营销时）contact.unsubscribed。email.opened 和 email.clicked 仅在该发信域名开启跟踪时才会触发。

如果还需要有人在 you@yourdomain.com 读信，Rovela 也提供托管邮箱和 webmail，那是和发信 API 不同的一面。见事务邮件 API + 托管邮箱和入站与出站 Email API。

上线清单

发信域名已验证；from 与之匹配（已验证域名的 Email API）
生产 Key 为 sending_access，仅服务端，绝不进浏览器或 App
每个由用户动作触发的发送都带稳定的 Idempotency-Key
同时提供 HTML 和 text（或使用已存储模板）
为退信和投诉配置 webhook，并校验签名（验证 Webhook 签名）
清楚 50 人上限和按收件人计费
个性化事务批量用 POST /emails/batch，营销群发走广播（broadcasts）

FAQ

事务邮件 API 等于 SMTP 吗？ 不等于。SMTP 是客户端或库直接说的传输协议；Email API 是接受 JSON 的 HTTP 接口，再由服务商向互联网其余部分走 SMTP。对比见Email API 与 SMTP 对比。应用迁移见从 SMTP 迁到 Email API。

Rovela 有官方 SDK 吗？ 没有。任何能发 HTTPS 请求的语言都可以（Email API）。

能用 POST /emails 做营销群发吗？ 你可以一封一封发，但名单展开、一键退订、主题抑制是广播负责的。品类划分见事务邮件与营销邮件。

sending_access 能做什么？ 足够通过 POST /emails 和 POST /emails/batch 入队。读信、改期、取消需要 full_access 或 Dashboard session。

200 表示用户已经收到了吗？ 不是——只表示已接受并入队。请用 GET /emails/:id、events 或 webhook。

先把 API 接上，投递给 Rovela

把事务邮件当成产品的一等能力：已验证域名、仅服务端的 sending_access、向 /emails 的 JSON POST、以及按逻辑发送稳定的幂等键。Rovela 负责排队、签名和投递；你的应用继续走 HTTP。准备好了就发送第一封邮件，再按上面的指南把其余场景接上。