邮件概览 | Nebutra Sailor Docs

Nebutra 事务邮件 — catalog 化的发送函数、本地预览和 Resend 投递。

Nebutra 通过 @nebutra/email 发送事务邮件。当前实现以 packages/integrations/email/src/index.ts 里的 EMAIL_TEMPLATE_CATALOG 为中心：它把每个公开发送函数映射到对应的预览产物；Resend 客户端只在真正发送邮件时才懒加载。

架构

Server action / route / job / webhook
  -> @nebutra/email 具名发送函数
  -> 品牌 HTML 邮件
  -> 懒加载 Resend 客户端
  -> 用户收件箱

没有 RESEND_API_KEY 时，仍然可以导入包、运行契约测试和校验本地预览。真实投递才需要 Resend 凭证。

内置目录

当前包维护 15 个模板：

Catalog ID	公开函数	预览产物
`welcome`	`sendWelcomeEmail`	`welcome-email.html`
`order-confirmation`	`sendOrderConfirmationEmail`	`order-confirmation-email.html`
`api-key-created`	`sendApiKeyCreatedEmail`	`api-key-created-email.html`
`quota-warning`	`sendQuotaWarningEmail`	`quota-warning-email.html`
`team-invitation`	`sendInviteEmail`	`team-invitation-email.html`
`magic-link`	`sendMagicLinkEmail`	`magic-link-email.html`
`contact-form-received`	`sendContactFormReceivedEmail`	`contact-form-received-email.html`
`checkout-completed`	`sendCheckoutCompletedEmail`	`checkout-completed-email.html`
`trial-ending`	`sendTrialEndingEmail`	`trial-ending-email.html`
`invoice-paid`	`sendInvoicePaidEmail`	`invoice-paid-email.html`
`payment-failed`	`sendPaymentFailedEmail`	`payment-failed-email.html`
`subscription-canceled`	`sendSubscriptionCanceledEmail`	`subscription-canceled-email.html`
`upcoming-invoice`	`sendUpcomingInvoiceEmail`	`upcoming-invoice-email.html`
`plan-changed`	`sendPlanChangedEmail`	`plan-changed-email.html`
`license-created`	`sendLicenseCreatedEmail`	`license-created-email.html`

快速开始

import { sendQuotaWarningEmail, sendWelcomeEmail } from "@nebutra/email";

await sendWelcomeEmail({
  to: user.email,
  firstName: user.firstName,
  orgName: org.name,
  dashboardUrl: "https://app.nebutra.com",
});

await sendQuotaWarningEmail({
  to: admin.email,
  orgName: org.name,
  metric: "api calls",
  used: 8100,
  limit: 10000,
  percentUsed: 81,
});

环境变量

变量	真实发送是否必需	说明
`RESEND_API_KEY`	是	Resend API key，只在发送时读取
`EMAIL_FROM`	否	发件人地址，默认 `Nebutra <[email protected]>`

RESEND_API_KEY 是密钥，不要提交到代码仓库。请放在 Vercel 环境变量、CI secrets 或密钥管理器中。

本地预览

用 mail-preview 工作区校验预览，不要手工改生成 HTML：

pnpm mail:check
pnpm mail:export

mail:check 校验每个目录项都有预览产物；mail:export 根据目录重新生成预览索引和 manifest。

Providers

Resend 配置、投递凭证和域名验证

Templates

Catalog ID、发送函数和必填参数示例

Testing

包测试、预览校验和无密钥验证

计费模型

配额提醒如何接入用量计量