Email Functionality

Introduction

Payload has a few email adapters that can be imported to enable email functionality. The @payloadcms/email-nodemailer package will be the package most will want to install. This package provides an easy way to use Nodemailer for email and won't get in your way for those already familiar.

The email adapter should be passed into the email property of the Payload Config. This will allow Payload to send auth-related emails for things like password resets, new user verification, and any other email sending needs you may have.

Configuration

Default Configuration

When email is not needed or desired, Payload will log a warning on startup notifying that email is not configured. A warning message will also be logged on any attempt to send an email.

Email Adapter

An email adapter will require at least the following fields:

Option	Description
`defaultFromName` *	The name part of the From field that will be seen on the delivered email
`defaultFromAddress` *	The email address part of the From field that will be used when delivering email

Official Email Adapters

Name	Package	Description
Nodemailer	@payloadcms/email-nodemailer	Use any Nodemailer transport, including SMTP, Resend, SendGrid, and more. This was provided by default in Payload 2.x. This is the easiest migration path.
Resend	@payloadcms/email-resend	Resend email via their REST API. This is preferred for serverless platforms such as Vercel because it is much more lightweight than the nodemailer adapter.

Nodemailer Configuration

Option	Description
`transport`	The Nodemailer transport object for when you want to do it yourself, not needed when transportOptions is set
`transportOptions`	An object that configures the transporter that Payload will create. For all the available options see the Nodemailer documentation or see the examples below

Use SMTP

Simple Mail Transfer Protocol (SMTP) options can be passed in using the transportOptions object on the email options. See the Nodemailer SMTP documentation for more information, including details on when secure should and should not be set to true.

Example email options using SMTP:

1import { buildConfig } from 'payload'
2import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
3
4export 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,
    },
  },
}),
18})

Example email options using nodemailer.createTransport:

1import { buildConfig } from 'payload'
2import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
3import nodemailer from 'nodemailer'
4
5export default buildConfig({
6  email: nodemailerAdapter({
7    defaultFromAddress: 'info@payloadcms.com',
8    defaultFromName: 'Payload',
9    // Any Nodemailer transport can be used
10    transport: nodemailer.createTransport({
11      host: process.env.SMTP_HOST,
12      port: 587,
13      auth: {
14        user: process.env.SMTP_USER,
15        pass: process.env.SMTP_PASS,
16      },
17    }),
18  }),
19})

Custom Transport:

You also have the ability to bring your own nodemailer transport. This is an example of using the SendGrid nodemailer transport.

1import { buildConfig } from 'payload'
2import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
3import nodemailerSendgrid from 'nodemailer-sendgrid'
4
5
6export default buildConfig({
7  email: nodemailerAdapter({
8    defaultFromAddress: 'info@payloadcms.com',
9    defaultFromName: 'Payload',
10    transportOptions: nodemailerSendgrid({
11      apiKey: process.env.SENDGRID_API_KEY,
12    }),
13  }),
14})

During development, if you pass nothing to nodemailerAdapter, it will use the ethereal.email service.

This will log the ethereal.email details to console on startup.

1import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
2
3export default buildConfig({
4  email: nodemailerAdapter(),
5})

Resend Configuration

The Resend adapter requires an API key to be passed in the options. This can be found in the Resend dashboard. This is the preferred package if you are deploying on Vercel because this is much more lightweight than the Nodemailer adapter.

Option	Description
apiKey	The API key for the Resend service.

1import { buildConfig } from 'payload'
2import { resendAdapter } from '@payloadcms/email-resend'
3
4export default buildConfig({
5  email: resendAdapter({
6    defaultFromAddress: 'dev@payloadcms.com',
7    defaultFromName: 'Payload CMS',
8    apiKey: process.env.RESEND_API_KEY || '',
9  }),
10})

Sending Mail

With a working transport you can call it anywhere you have access to Payload by calling payload.sendEmail(message). The message will contain the to, subject and html or text for the email being sent. Other options are also available and can be seen in the sendEmail args. Support for these will depend on the adapter being used.

1// Example of sending an email
2const email = await payload.sendEmail({
3  to: 'test@example.com',
4  subject: 'This is a test email',
5  text: 'This is my message body',
6})

Using multiple mail providers

Payload supports the use of a single transporter of email, but there is nothing stopping you from having more. Consider a use case where sending bulk email is handled differently than transactional email and could be done using a hook.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.