用 Node.js 发送邮件

前提条件

您需要一个 Rovela 账号（免费，无需绑卡）、仪表板中的 API Key，以及一个已验证的发信域名。以下示例假设使用 Node.js 18 或更高版本，因为它内置了全局 fetch。相同的代码在安装 node-fetch 后可用于 Node 16，在 Deno 或 Bun 中无需任何修改。

最简发送

向 /emails 发送一个 POST 请求，在 Authorization 头中包含您的 API Key，请求体为 JSON。响应中包含消息 ID，可供后续查询使用。

const res = await fetch('https://api.rovela.dev/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer re_your_api_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Welcome aboard',
    html: '<p>Thanks for signing up. Your account is ready.</p>',
  }),
})

const { id } = await res.json()
console.log('Sent:', id)

添加重试和幂等性

在循环之前生成一次幂等键，并在每次尝试中复用它。这样，网络错误或 5xx 响应都会触发重试，但无论有多少次尝试在服务器端成功，同一封邮件永远只会被发送一次。

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function sendWithRetry(payload, retries = 3) {
  const key = crypto.randomUUID()
  for (let i = 0; i <= retries; i++) {
    const res = await fetch('https://api.rovela.dev/emails', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer re_your_api_key',
        'Content-Type': 'application/json',
        'Idempotency-Key': key,  // same key on every attempt
      },
      body: JSON.stringify(payload),
    })
    if (res.status < 500) return res          // 2xx or 4xx — stop
    await sleep(Math.min(1000 * 2 ** i, 8000)) // backoff, capped
  }
  throw new Error('send failed after ' + retries + ' retries')
}

存储消息 ID

Rovela 返回的 ID 将发送操作与 Webhook 和日志中的投递事件关联起来。请在您自己的数据库中将它与相应的业务记录关联存储。当收到 email.bounced 或 email.complained 的 Webhook 时，payload 中的消息 ID 会告诉您确切对应哪次发送，以及需要更新哪位用户的状态。

环境变量

永远不要将 API Key 写入源代码。使用 process.env.ROVELA_API_KEY，在开发环境中通过 dotenv 从 .env 文件加载，在生产环境中从部署平台的密钥存储中加载。如果 Key 意外泄露，立即在 Rovela 仪表板中轮换；新 Key 立即生效，旧 Key 同时失效。