邮件通知 API（2026）：用 Rovela HTTP 发送告警与系统通知

用 Rovela 的邮件 API 发送系统与产品通知：按事故设置 Idempotency-Key、仅服务端 sending_access、摘要邮件和退信 webhook——不是通讯。

面向「系统已经知道的那些事」的邮件通知 API

邮件通知 API 让应用把内部事件——指标越过阈值、任务失败、故障开启、夜间摘要就绪——变成一封短而可信、需要有人采取行动的邮件。它仍然是事务邮件：一个（或少数）收件人，内容由对方触发或由其负责，通过 HTTP 发出。它不是促销通讯。

本文聚焦系统和产品通知。事务邮件的总述见事务邮件 API；SaaS 生命周期邮件（验证码、邀请、收据）见SaaS 应用的 Email API。某一种 cron 库怎么接线，属于那些集成文章，不在这里展开。可以从Email API产品页、快速开始、发送邮件 API和身份认证入手。

本系列相关产品指南：

什么时候通知应该走邮件

邮件适合那些必须送到「没盯着你仪表盘的人」的通知：值班备份、创始人、客户的账单联系人、每周运维摘要。应用内铃铛和 Slack 对已经在线的人更快；邮件是可留存的副本。

适合的例子：

监控流水线里的阈值和异常告警（事务邮件产品页把系统告警列为典型用途）。
「后台任务失败了 N 次」发给负责团队。
在发送时刻才拼出 HTML 的每日或每周摘要。
面向客户、但不是营销的通知：「你的导出已完成」「有新设备登录」。

名单式公告请走广播。若正文已经定稿、只需「09:00 投递」，用 scheduled_at（定时发送邮件）。若必须在 09:00 查询新鲜指标，请跑自己的调度器，到点再 POST /emails——Rovela 不托管你的 cron。

一次通知发送

把 ROVELA_API_KEY（sending_access）和 MAIL_FROM 放在 Worker 上。使用按窗口或按事故的幂等键，避免重试和重叠告警把同一封信乘成多封：

import json, os, urllib.request

def send_transactional(*, to, subject, html, text, idempotency_key, tags=None):
    body = {
        "from": os.environ["MAIL_FROM"],
        "to": to,
        "subject": subject,
        "html": html,
        "text": text,
    }
    if tags:
        body["tags"] = tags
    req = urllib.request.Request(
        "https://api.rovela.dev/emails",
        data=json.dumps(body).encode(),
        headers={
            "Authorization": "Bearer " + os.environ["ROVELA_API_KEY"],
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        method="POST",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode())


# 示例：每个事故一封，而不是监控的每次重试一封
send_transactional(
    to=os.environ["ONCALL_EMAIL"],
    subject=f"[Acme] incident {incident_id} is open",
    html=f"<p>Incident <b>{incident_id}</b> is open. {summary}</p>",
    text=f"Incident {incident_id} is open. {summary}",
    idempotency_key=f"incident-open:{incident_id}",
    tags={"kind": "incident-open", "incident": incident_id},
)

若摘要在 Worker 重启后也不能发第二次，请按业务窗口做键（如 ops-digest:{yyyy-mm-dd}），见邮件 API 的幂等键。一次任务里多封个性化摘要走批量事务邮件 API（最多 100 封，batch 端点不接受模板）。

如果值班可能会回复，把 reply_to 设到有人看的邮箱（事务邮件 API + 托管邮箱）。同时发 HTML 和 text：很多手机锁屏预览的是 text。

可运维性

200 表示已入队，不是「值班已经读过」。关键告警请同时走寻呼；并用 webhook（email.bounced、email.failed）避免值班地址退信却被静默丢掉（事务邮件 Webhook，处理退信）。
遵守 50 人上限。「把事故信发给全公司」通常形态就不对；用 batch 按 100 封一组展开，或仅在内容真的是同一封名单邮件时使用广播。
不要把 full_access 放在监控进程上。发信足够。状态交给独立工具或 webhook。
使用 tags（kind、incident、env），方便你在糟糕的夜里重建时间线。

从到来的 Rovela 事件出发的自动化（退信 → 工单）见用 Webhook 驱动邮件自动化；本文是另一个方向：你的系统事件 → 邮件。

FAQ

通知进程能走邮箱 SMTP 吗？ 只有在你能接受邮箱限制（只能以自身发送、同一客户端地址每分钟 30 封）且不需要那么强的程序化工具时才可以。SMTP 页写明：程序化、有一定量的发信请用 HTTP API（SMTP，HTTP 邮件 API）。

这和「用 webhook 驱动发信」有什么不同？ 后者从供应商事件（Stripe、Shopify，或 Rovela 自己）开始。通知 API 调用从你的指标、任务或事故开始。

告警正文里能放 PII 或秘密吗？ 最好只放短摘要，再链到需要登录的管理页面。邮件会在比数据库更多的地方被保存。

告警要不要开打开跟踪？ email.opened / email.clicked 只在该发信域名开启跟踪时才会触发。很多团队会给安全和运维邮件关掉跟踪；不要把「没有打开事件」当成「没人看到告警」。

呼叫到人，邮件入队

当系统已经知道出事了（或事情做完了），用窗口级或事故级幂等键，以及仅服务端的发信 Key，调用 POST /emails。这就是邮件通知 API：朴素、可靠、容易审计。