@wecode-team/email-verify

We0 邮件 SDK —— 验证码收发、自定义邮件、预置模板，开箱即用。零依赖，自带重试和错误分类。

安装

npm install @wecode-team/email-verify
# 或
pnpm add @wecode-team/email-verify
# 或
yarn add @wecode-team/email-verify

快速开始

import { sendCode, verifyCode, sendEmail, template } from "@wecode-team/email-verify"

// 1. 发送验证码
await sendCode("[email protected]")

// 2. 校验验证码
const result = await verifyCode("[email protected]", "123456")
console.log(result.verified) // true

// 3. 发送自定义邮件
await sendEmail({
  to: "[email protected]",
  subject: "欢迎加入",
  html: template.welcome("张三", "MyApp"),
})

API

sendCode(email, retry?)

发送 6 位验证码到指定邮箱。

• 参数：email: string，retry?: RetryOptions
• 返回：Promise<{ message: string }>
• 频率限制：同一邮箱 60 秒内只能发送一次
• 有效期：验证码 10 分钟内有效

verifyCode(email, code, retry?)

校验邮箱验证码。

• 参数：email: string，code: string（6 位），retry?: RetryOptions
• 返回：Promise<{ verified: boolean }>
• 说明：验证码为一次性使用，校验成功后自动失效

sendEmail(options, retry?)

发送自定义邮件。

• 参数：

  interface SendEmailOptions {
    to: string          // 收件人邮箱
    subject: string     // 邮件主题
    html?: string       // HTML 内容（与 text 至少提供一个）
    text?: string       // 纯文本内容
    locale?: "en" | "zh"
  }

• 返回：Promise<{ messageId: string }>

createClient(options?)

创建自定义配置的客户端实例。默认裸函数使用 https://we0.ai，通过 createClient 可切换到自建服务。

import { createClient } from "@wecode-team/email-verify"

const client = createClient({
  baseURL: "https://my-app.com",
  timeout: 5000,
  retry: { retries: 3, delay: 500 },
})

await client.sendCode("[email protected]")
await client.sendEmail({ to: "[email protected]", subject: "Hi", text: "Hello" })

配置项：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | baseURL | string | "https://we0.ai" | API 基础地址 | | timeout | number | 10000 | 请求超时（毫秒） | | retry | RetryOptions | { retries: 2, delay: 1000, backoff: 2 } | 默认重试配置 |

重试机制

所有请求默认自动重试 2 次（共 3 次），指数退避（1s → 2s）。

可重试错误：网络错误、超时、5xx 服务端错误

不可重试错误：400 参数错误、429 频率限制等业务错误，立即抛出

// 自定义重试
await sendCode("[email protected]", { retries: 5, delay: 500, backoff: 1.5 })

// 关闭重试
await sendCode("[email protected]", { retries: 0 })

错误处理

import { sendCode, EmailVerifyError, ErrorCode } from "@wecode-team/email-verify"

try {
  await sendCode("[email protected]")
} catch (err) {
  if (err instanceof EmailVerifyError) {
    switch (err.code) {
      case ErrorCode.RATE_LIMIT:
        console.log("发送过于频繁")
        break
      case ErrorCode.NETWORK:
        console.log("网络错误")
        break
      case ErrorCode.TIMEOUT:
        console.log("请求超时")
        break
      case ErrorCode.SERVER_ERROR:
        console.log("服务端错误")
        break
    }

    // 也可以直接判断是否可重试
    if (err.isRetryable) {
      // 可重试的错误
    }
  }
}

ErrorCode 枚举

| 枚举值 | 数值 | 说明 | |--------|------|------| | NETWORK | 0 | 网络错误（断网、DNS 失败） | | TIMEOUT | 1 | 请求超时 | | INVALID_PARAMS | 400 | 参数校验失败 | | UNAUTHORIZED | 401 | 未授权 | | FORBIDDEN | 403 | 禁止访问 | | NOT_FOUND | 404 | 资源不存在 | | RATE_LIMIT | 429 | 频率限制 | | SERVER_ERROR | 500 | 服务端内部错误 | | SERVICE_UNAVAILABLE | 503 | 服务不可用 |

邮件模板

预置 4 个常用模板，内置 XSS 转义：

import { sendEmail, template } from "@wecode-team/email-verify"

// 欢迎邮件
await sendEmail({
  to: "[email protected]",
  subject: "欢迎加入 MyApp",
  html: template.welcome("张三", "MyApp"),
})

// 密码重置
await sendEmail({
  to: "[email protected]",
  subject: "重置密码",
  html: template.resetPassword("https://my-app.com/reset?token=abc", "30 分钟"),
})

// 订单确认
await sendEmail({
  to: "[email protected]",
  subject: "订单确认",
  html: template.orderConfirmation("12345", [
    { name: "商品 A", price: "¥49" },
    { name: "商品 B", price: "¥50" },
  ], "¥99"),
})

// 通用通知（带操作按钮）
await sendEmail({
  to: "[email protected]",
  subject: "部署完成",
  html: template.notification("部署成功", "您的项目已上线。", "https://my-app.com", "查看项目"),
})

模板函数

| 函数 | 参数 | 说明 | |------|------|------| | template.welcome(name, productName) | 用户名, 产品名 | 欢迎注册邮件 | | template.resetPassword(link, expiresIn?) | 重置链接, 过期时间 | 密码重置邮件 | | template.orderConfirmation(orderId, items, total) | 订单号, 商品列表, 总额 | 订单确认邮件 | | template.notification(title, body, actionUrl?, actionText?) | 标题, 正文, 链接, 按钮文字 | 通用通知邮件 |

环境兼容性

• Node.js >= 18（内置 fetch）
• Deno / Bun / Edge Runtime

License

MIT