GroundmailDocs

Payload CMS email with Groundmail

Payload apps need transactional email for auth and notifications. Groundmail ships a Payload 3 email adapter: groundmailAdapter from groundmail-payload (also groundmail/payload).

Install

npm install groundmail-payload groundmail
GROUNDMAIL_API_KEY=gm_your_key_here

Payload email adapter

// payload.config.ts
import { buildConfig } from 'payload'
import { groundmailAdapter } from 'groundmail-payload'

export default buildConfig({
  email: groundmailAdapter({
    defaultFromAddress: 'noreply@yourdomain.com',
    defaultFromName: 'Acme',
    // apiKey: process.env.GROUNDMAIL_API_KEY,
  }),
  // collections, …
})

Payload then routes auth mail and payload.sendEmail() through Groundmail (product=payload tag).

Options

Option Purpose
defaultFromAddress Verified From address (required)
defaultFromName Display name (required)
apiKey Falls back to GROUNDMAIL_API_KEY
baseUrl Override API base (tests / self-hosted)
overrideRecipientAddress Force all mail to one address (local/dev)
client Inject a Groundmail instance (tests)

Nodemailer transport (optional)

If you prefer Nodemailer + @payloadcms/email-nodemailer:

npm install groundmail-nodemailer groundmail nodemailer
import nodemailer from 'nodemailer'
import { createGroundmailTransport } from 'groundmail-nodemailer'

export const transport = nodemailer.createTransport(
  createGroundmailTransport({
    apiKey: process.env.GROUNDMAIL_API_KEY!,
  }),
)

Wire that transport into Payload’s Nodemailer email adapter for your Payload major version. Prefer the first-party groundmailAdapter when you can.

Direct SDK

import { Groundmail } from 'groundmail'

const tx = new Groundmail(process.env.GROUNDMAIL_API_KEY!)

await tx.emails.send({
  from: 'noreply@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Welcome.</p>',
})