邮件发送

概览

@01mvp/email 是一个邮件发送工具，帮你用代码给用户发邮件。当前支持 Resend 和 Zeabur Email，你不需要自己维护邮件服务器。

• 发送验证邮件 -- 用户注册时发验证码或验证链接
• 发送密码重置邮件 -- 用户忘记密码时发重置链接
• 发送邀请邮件 -- 团队成员邀请
• 发送通知邮件 -- 订单确认、活动通知等
• 反馈邮件 -- 把站内反馈直接发到指定收件箱
• 批量发送 -- Zeabur Email REST API 支持批量任务

邮件模板预览

本地开发时可以在网页里统一查看邮件模板样式，不需要真实发送邮件。

pnpm dev

启动后打开：

http://localhost:7001/admin/email

预览页支持切换模板和语言，也会展示邮件主题、纯文本版本，以及带 unsubscribeUrl 时生成的退订邮件头。常用入口：

http://localhost:7001/admin/email?template=magicLink&locale=zh
http://localhost:7001/admin/email?template=forgotPassword&locale=en

环境变量

ORDER_NOTIFICATION_EMAIL 不是必填变量。早期产品建议先用 CONTACT_EMAIL 统一接收反馈和订单通知；只有当订单通知需要发给不同邮箱或多个邮箱时，再配置它。多个邮箱可以用逗号、空格或分号分隔。

Resend 配置（推荐）

RESEND_API_KEY=re_xxxxxxxxxxxxx
EMAIL_FROM=noreply@yourdomain.com

代码示例

import { createEmailProvider } from "@01mvp/email";

const provider = createEmailProvider("resend", {
  apiKey: process.env.RESEND_API_KEY!,
  defaultFrom: process.env.EMAIL_FROM,
});

await provider.send({
  to: "user@example.com",
  subject: "验证邮箱",
  html: "<p>点击链接验证</p>",
});

Zeabur Email 配置（备选）

ZEABUR_EMAIL_API_KEY=zs_xxxxxxxxxxxxx
EMAIL_FROM=contact@yourdomain.com
CONTACT_EMAIL=contact@yourdomain.com
# 可选：订单通知单独投递到这些邮箱
ORDER_NOTIFICATION_EMAIL=orders@yourdomain.com,finance@yourdomain.com

代码示例

import { createEmailProvider } from "@01mvp/email";

const provider = createEmailProvider("zeabur", {
  apiKey: process.env.ZEABUR_EMAIL_API_KEY!,
  defaultFrom: process.env.EMAIL_FROM,
});

await provider.send({
  to: "contact@yourdomain.com",
  subject: "用户反馈",
  text: "反馈内容",
  replyTo: "user@example.com",
  tags: {
    type: "feedback",
    category: "bug",
  },
});

Zeabur Email 限制和价格

Zeabur REST API 的限制：

• API 基础地址是 https://api.zeabur.com/api/v1/zsend，请求用 Bearer Token 认证
• 单封邮件接口是 POST /emails，html 和 text 至少需要一个
• 单封邮件的 to + cc + bcc 总收件人数最多 50 人
• 主题最长 998 个字符，HTML 和文本内容各最大 5 MB
• 邮件总大小最大 10 MB，附件最多 10 个，单个附件最大 10 MB
• 批量发送接口单次最多 100 封
• 429 和 5xx 这类临时错误建议指数退避重试；400 / 403 不要反复重试

Zeabur 价格页当前展示的 Email 配额：

新用户默认 100 封/天，完成域名验证后默认提升到 1,000 封/天。实际可用额度以 Zeabur 控制台展示为准。

工作原理

1. 你的代码调用 createEmailProvider('zeabur') 或 createEmailProvider('resend')，传入 API Key
2. 调用 .send() 方法，告诉它发给谁、标题是什么、邮件内容（HTML 格式）
3. 底层拼装好邮件，通过对应服务的 API 发出去
4. 返回一个结果告诉你成功还是失败，以及失败原因

相关资源

• Zeabur Email 文档
• Zeabur Email REST API
• Zeabur 价格页
• Resend 官方文档