HTTP 邮件 API（2026）：用 HTTPS 通过 Rovela 发送事务邮件

用 HTTPS 和 JSON 发送事务邮件，而不必自己开 SMTP 套接字：POST /emails、Bearer API Key、Idempotency-Key，以及和 Rovela 邮箱 SMTP 的区别。

用 HTTPS 发信，而不是自己连 25 端口

HTTP 邮件 API 让你用调用其他后端的方式发送事务邮件：HTTPS、Bearer token、JSON 正文。应用里不必再打开 SMTP 会话，不必自己谈 EHLO / STARTTLS / AUTH，也不必维护发信 socket 池。Rovela 的Email API就是一个端点——POST https://api.rovela.dev/emails——负责入队、用你的域名密钥做 DKIM 签名，并返回 id。

这是「用 HTTP 发信」的协议向介绍。它不是让 AI 编程助手通过 HTTP 发信（面向编程助手的用法），不是Email API 与 SMTP 对比里的选型对比，也不是5 分钟发送第一封邮件的五分钟上手。如果正在把 Nodemailer、PHPMailer 的 SMTP 迁走，请看从 SMTP 迁到 Email API。若要先弄清事务邮件是什么，见事务邮件 API。

可以从Email API产品页、快速开始、发送邮件 API和身份认证入手。 Rovela 也为人和邮件客户端提供邮箱 SMTP（mx.rovela.dev 端口 465），那是另一条路径，下文会区分。

本系列相关产品指南：

HTTP 请求长什么样

用 Authorization: Bearer re_your_api_key 认证（身份认证）。正文是扁平 JSON：from、to、subject，以及 html、text 或 template 至少之一。

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": "you@example.com",
    "subject": "Hello from Rovela",
    "html": "<p>It worked.</p>",
    "text": "It worked."
  }'

成功响应形如 {"object": "email", "id": "9f1c2e40-..."}。这个 200 表示已接受并准备投递，不是「已经在收件箱里」。投递在后台进行，你的请求不会卡在对方邮件服务器上（Email API，快速开始）。

用 Node 或 Python 发同样是一次普通 HTTP 调用：

const res = await fetch("https://api.rovela.dev/emails", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.ROVELA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": `signup-verify:${userId}:${codeId}`,
  },
  body: JSON.stringify({
    from: process.env.MAIL_FROM, // e.g. "Acme <no-reply@yourdomain.com>"
    to: user.email,
    subject: `Your Acme code: ${code}`,
    html: `<p>Your verification code is <b>${code}</b>. It expires in 10 minutes.</p>`,
    text: `Your verification code is ${code}. It expires in 10 minutes.`,
    tags: { kind: "signup-otp", userId },
  }),
});
if (!res.ok) {
  const err = await res.json();
  throw new Error(`Rovela ${res.status}: ${err.message}`);
}
const { id } = await res.json(); // accepted and queued — not yet delivered

语言向的走读已经写在在 Node.js 中发送邮件和用 Python 发送邮件；本文只谈这些指南共用的 HTTP 约定。

应用里的 HTTP 与 SMTP

关注点	应用直连 SMTP	HTTP 邮件 API
传输	TCP 连 25、465 或 587	HTTPS 到 `api.rovela.dev`
认证	`AUTH` / 邮箱密码	`Authorization: Bearer` API Key
载荷	在库里拼 MIME	JSON 字段（`html`、`text`、`attachments`）
超时 / 重试	多半要自己处理	重试该 `POST`；加上 `Idempotency-Key`
投递状态	解析 DSN 或翻日志	`GET /emails/:id`、events 或 webhook
出站防火墙	25 端口经常被封	443 通常是通的

端口分工见SMTP 端口 25、465、587。Rovela 的SMTP 产品页面向企业邮箱：主机 mx.rovela.dev，端口 465（隐式 TLS），用户名为邮箱完整地址，密码为设备凭证。一个邮箱只能以自己的地址发送，文档中的上限是每封最多 50 个收件人、同一客户端地址每分钟 30 封。该页也写明：程序化、有一定量的发信请用 HTTP API（并获得跟踪、日志和 webhook）。不要把邮箱 SMTP 当成隐秘的高并发应用中继。

让 HTTP 发信变得安全

已验证的 from。 未验证域名会以 400 拒绝并指出域名。见已验证域名的 Email API。
sending_access 只放服务端。 不要放进浏览器、移动应用或公开仓库。泄露的发信 Key 等于有人能以你的域名发信（身份认证）。
凡会重试的请求都加 Idempotency-Key。 队列、Serverless 重试、用户双击都会再次进入同一次逻辑发送。Key 在 24 小时内有效，最长 256 字符（邮件 API 的幂等键，幂等指南）。
生产发信用 sending_access。 需要读信、管理域名、模板或 webhook 的工具再用 full_access。
结果也用 HTTP 看。 注册 webhook（事务邮件 Webhook），或用 full_access 调用 GET /emails/:id。

实际会用到的可选字段：reply_to、cc / bcc（计入 50 人上限和额度）、scheduled_at、tags、attachments，以及已存储的 template。批量发送是另一个 HTTP 端点：POST /emails/batch，见批量事务邮件 API。

什么时候不该用 HTTP API

人在 Outlook、Apple Mail、Thunderbird 里写信，应使用邮箱的 SMTP/IMAP，而不是 API Key（SMTP，事务邮件 API + 托管邮箱）。
面向名单或分段的营销发送应走广播，而不是把事务 POST 紧循环（事务邮件与营销邮件）。
正文已经定稿，只需要「稍后投递」、且不想常驻 Worker 时——scheduled_at 仍然是 HTTP，只是延迟投递（定时发送邮件）。

FAQ

必须安装库吗？ 不必。curl、fetch、httpx、net/http 或任何 HTTPS 客户端即可（安装说明）。

能从浏览器直接调 API 吗？ 不应该。客户端里的 sending_access 等于给自己的域名准备好了滥发工具。中间加一层服务器（Email API 集成）。

这和「用 curl 发信」是一回事吗？ curl 只是一种 HTTP 客户端，契约相同；curl 的参数、错误与取消示例在用 curl 发送邮件。

怎么知道邮件已投递？ 用 full_access 查询 GET /emails/:id，或订阅 email.delivered / email.bounced webhook。产品页提到，接收服务器做出决定后，webhook 通常大约在一分钟内推送到（Email API）。

回复怎么收？ 有的产品还要入站。见入站与出站 Email API和入站邮件 API 与 Webhook。

应用发信走 HTTPS

让服务端调用 POST /emails，把 sending_access 放在环境变量里，由 Rovela 对互联网其余部分说 SMTP。这就是 HTTP 邮件 API：一次请求、一个 message id，以及入队之后的 webhook。