邮件功能

简介

Payload 提供了几个邮件适配器，可以通过导入来启用邮件功能。大多数用户会想要安装 @payloadcms/email-nodemailer 这个包。该包提供了一种简单的方式来使用 Nodemailer 发送邮件，对于已经熟悉 Nodemailer 的用户来说不会造成任何困扰。

邮件适配器应该通过 email 属性传递给 Payload 配置。这将允许 Payload 发送与认证相关的邮件，例如密码重置、新用户验证，以及你可能需要的任何其他邮件发送需求。

配置

默认配置

当不需要或不想使用邮件功能时，Payload 会在启动时记录一个警告，通知用户邮件功能未配置。任何尝试发送邮件的操作也会记录警告信息。

邮件适配器

一个邮件适配器至少需要以下字段：

选项描述
defaultFromName *邮件发件人字段中显示的名称部分
defaultFromAddress *发送邮件时使用的发件人邮箱地址

官方邮件适配器

名称包描述
Nodemailer@payloadcms/email-nodemailer使用任何 Nodemailer 传输方式，包括 SMTP、Resend、SendGrid 等。这是 Payload 2.x 默认提供的适配器，是最简单的迁移路径。
Resend@payloadcms/email-resend通过 Resend 的 REST API 发送邮件。对于 Vercel 等无服务器平台更推荐使用此适配器，因为它比 nodemailer 适配器更加轻量级。

Nodemailer 配置

OptionDescription
transport当你想自行配置时使用的 Nodemailer transport 对象，如果设置了 transportOptions 则不需要此选项
transportOptions用于配置 Payload 将创建的传输器的对象。所有可用选项请参阅 Nodemailer 文档 或查看下方示例

使用 SMTP

简单邮件传输协议 (SMTP) 选项可以通过 email 选项中的 transportOptions 对象传递。更多信息请参阅 Nodemailer SMTP 文档，包括何时应将 secure 设置为 true 的详细信息。

使用 SMTP 的 email 配置示例:

import { buildConfig } from 'payload'
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'

export default buildConfig({
  email: nodemailerAdapter({
    defaultFromAddress: 'info@payloadcms.com',
    defaultFromName: 'Payload',
    // Nodemailer transportOptions
    transportOptions: {
      host: process.env.SMTP_HOST,
      port: 587,
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS,
      },
    },
  }),
})

使用 nodemailer.createTransport 的邮件配置示例：

import { buildConfig } from 'payload'
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
import nodemailer from 'nodemailer'

export default buildConfig({
  email: nodemailerAdapter({
    defaultFromAddress: 'info@payloadcms.com',
    defaultFromName: 'Payload',
    // 可以使用任何 Nodemailer 传输方式
    transport: nodemailer.createTransport({
      host: process.env.SMTP_HOST,
      port: 587,
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS,
      },
    }),
  }),
})

自定义传输方式：

你也可以使用自己的 nodemailer 传输方式。以下是使用 SendGrid nodemailer 传输的示例。

import { buildConfig } from 'payload'
import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
import nodemailerSendgrid from 'nodemailer-sendgrid'

export default buildConfig({
  email: nodemailerAdapter({
    defaultFromAddress: 'info@payloadcms.com',
    defaultFromName: 'Payload',
    transportOptions: nodemailerSendgrid({
      apiKey: process.env.SENDGRID_API_KEY,
    }),
  }),
})

在开发环境中，如果你不向 nodemailerAdapter 传递任何参数，它将使用 ethereal.email 服务。

这会在启动时将 ethereal.email 的详细信息打印到控制台。

import { nodemailerAdapter } from '@payloadcms/email-nodemailer'

export default buildConfig({
  email: nodemailerAdapter(),
})

Resend 配置

Resend 适配器需要在选项中传入 API 密钥。该密钥可以在 Resend 仪表板中找到。如果你部署在 Vercel 上，这是首选的包，因为它比 Nodemailer 适配器更轻量。

选项描述
apiKeyResend 服务的 API 密钥。
import { buildConfig } from 'payload'
import { resendAdapter } from '@payloadcms/email-resend'

export default buildConfig({
  email: resendAdapter({
    defaultFromAddress: 'dev@payloadcms.com',
    defaultFromName: 'Payload CMS',
    apiKey: process.env.RESEND_API_KEY || '',
  }),
})

发送邮件

配置好传输器后，你可以在任何能访问 Payload 的地方通过调用 payload.sendEmail(message) 来发送邮件。message 参数包含要发送邮件的 to（收件人）、subject（主题）以及 html 或 text（邮件正文）。其他选项也可用，具体取决于所使用的适配器。

// 发送邮件示例
const email = await payload.sendEmail({
  to: 'test@example.com',
  subject: 'This is a test email',
  text: 'This is my message body',
})

使用多个邮件提供商

Payload 支持使用单一的邮件传输器，但你也可以配置多个。例如，批量邮件发送可能与事务性邮件处理方式不同，可以通过 hook 来实现。