Raypx

@raypx/email 提供基于传输层抽象的邮件发送能力，支持同步和异步模板渲染。

核心导出

import {
  createSender,
  sendMail,
  renderTemplate,
  renderTemplateAsync,
} from "@raypx/email"

导出	说明
`createSender()`	创建邮件发送器
`sendMail()`	直接发送邮件
`renderTemplate()`	渲染邮件模板
`renderTemplateAsync()`	异步渲染邮件模板（统一返回 Promise）

传输层

邮件发送通过 MailTransport 接口抽象，任何实现了 send() 方法的对象都可以作为传输层。

interface MailTransport {
  send(message: MailMessage): Promise<MailSendResult>
}

createSender()

创建一个绑定了特定传输层的发送器。

import { createSender } from "@raypx/email"

const sender = createSender({
  transport: {
    async send(message) {
      // 使用 Resend、Nodemailer 或任何邮件服务
      return { ok: true, id: "msg_xxx" }
    },
  },
})

await sender.send({
  from: { email: "noreply@example.com", name: "Raypx" },
  to: { email: "user@example.com" },
  subject: "Welcome",
  html: "<h1>Hello!</h1>",
})

sendMail()

一次性发送邮件。

import { sendMail } from "@raypx/email"

const result = await sendMail(message, { transport })

发送结果

type MailSendResult =
  | { ok: true; id?: string; data?: unknown }
  | { ok: false; error: string }

模板

邮件模板是一个接收输入数据、返回渲染结果的函数。

EmailTemplate

同步模板：

type EmailTemplate<TInput> = (input: TInput) => EmailTemplateResult

type EmailTemplateResult = {
  subject: string
  html: string
  text?: string
}

AsyncEmailTemplate

异步模板（例如使用 React Email 时 render() 返回 Promise）：

type AsyncEmailTemplate<TInput> = (
  input: TInput,
) => AsyncEmailTemplateResult | Promise<AsyncEmailTemplateResult>

type AsyncEmailTemplateResult = {
  subject: string
  html: string | Promise<string>
  text?: string
}

renderTemplate()

渲染模板，根据模板类型自动判断同步或异步调用。

import { renderTemplate } from "@raypx/email"

const result = renderTemplate(template, input)
// result 可能是 EmailTemplateResult 或 Promise<AsyncEmailTemplateResult>

renderTemplateAsync()

统一以异步方式渲染模板，始终返回 Promise<EmailTemplateResult>。

import { renderTemplateAsync } from "@raypx/email"

const { subject, html, text } = await renderTemplateAsync(template, input)

适用于不确定模板是同步还是异步的场景。

邮件消息

type MailMessage = {
  from: MailAddress              // 发件人
  to: MailAddress | MailAddress[] // 收件人（支持多个）
  subject: string
  html?: string
  text?: string
  replyTo?: MailAddress
  headers?: Record<string, string>
}

type MailAddress = {
  email: string
  name?: string
}

环境变量

变量	类型	必填	说明
`RESEND_API_KEY`	`string`	否	Resend API 密钥
`RESEND_FROM_EMAIL`	`email`	否	Resend 发件地址
`EMAIL_FROM`	`email`	否	通用发件地址
`EMAIL_TEMPLATES_BASE_URL`	`url`	否	邮件模板中链接的基础 URL

@raypx/email

On this page