Skip to content
Browse the docs

Frameworks and agents · Published 2026-11-11 · Updated 2026-11-11 · AgentiSend

Send email from Payload CMS

To send email from Payload CMS through an API, give its Nodemailer adapter the nodemailer-agentisend-transport; payload.sendEmail posts to POST /emails.

To send email from Payload CMS through an API, give its Nodemailer adapter the nodemailer-agentisend-transport; payload.sendEmail posts to POST /emails. The adapter is @payloadcms/email-nodemailer. Payload's own mail, such as the forgot-password and verify-account emails of an auth collection, goes the same way, because Payload sends all of it through the one adapter in buildConfig. No SMTP host, port or password is involved: the transport posts each message over HTTPS and returns the message id.

Install

npm install @payloadcms/email-nodemailer nodemailer nodemailer-agentisend-transport

Environment

Put two values in the .env Payload already reads: AGENTISEND_API_KEY, a key created with sending_access for the CMS alone, and MAIL_FROM, the address Payload uses when a message names no sender, on a domain you have verified here. The transport reads the key itself; MAIL_FROM goes into the adapter config below. AGENTISEND_BASE_URL is optional and points the transport at another API host, such as a local one in tests.

payload.config.ts

import { buildConfig } from 'payload';
import { nodemailerAdapter } from '@payloadcms/email-nodemailer';
import nodemailer from 'nodemailer';
import { createTransport } from 'nodemailer-agentisend-transport';

export default buildConfig({
  // ...collections, db, secret
  email: nodemailerAdapter({
    defaultFromAddress: process.env.MAIL_FROM!,
    defaultFromName: 'Your app',
    transport: nodemailer.createTransport(createTransport()),
    skipVerify: true,
  }),
});

Payload's email overview (read 11 November 2026) describes transport as the Nodemailer transport object "for when you want to do it yourself", which is this case. Pass the transporter as transport, not transportOptions: transportOptions is for an SMTP server Payload connects to.

skipVerify: true skips the adapter's startup check. That check opens an SMTP connection on an SMTP transport; this transport has no connection to open, so Nodemailer answers it with false and nothing is checked. A test in the transport's package calls verify() and sendMail() the way the adapter does, against a local fake of the API.

Send from a hook or an endpoint

await payload.sendEmail({
  to: order.customerEmail,
  subject: `Order ${order.id} shipped`,
  html: `<p>Your order ${order.id} is on its way.</p>`,
});

When from is left out, the adapter fills it as Your app <MAIL_FROM>. The call resolves to Nodemailer's info object, and info.messageId is the id from POST /emails. Keep it: GET /emails/{id} says where that message is now, and GET /emails/{id}/explain says why when it was not delivered.

curl -sS -X GET https://api.agentisend.com/emails/9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42 \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"
200
{
  "api_key_id": "example",
  "attachments": [],
  "bcc": [],
  "cc": [],
  "created_at": "2026-09-04T09:14:00.000Z",
  "domain": "example",
  "from": "example",
  "headers": {},
  "html": "example",
  "id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "last_event": "queued",
  "message_id": "example",
  "object": "email",
  "provider_message_id": "example",
  "reply_to": [],
  "scheduled_at": "2026-09-04T09:14:00.000Z",
  "status": "queued",
  "subject": "example",
  "tags": {},
  "template_id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "template_version": -9007199254740991,
  "text": "example",
  "to": [],
  "updated_at": "2026-09-04T09:14:00.000Z",
  "warnings": []
}
Response

Forgot-password and verify emails

An auth collection sends two emails of its own, and both reach the adapter above with no extra wiring. Payload's authentication email page (read 11 November 2026) lets a collection replace their subject and body:

// collections/Users.ts
export const Users = {
  slug: 'users',
  auth: {
    verify: {
      generateEmailSubject: () => 'Confirm your email',
      generateEmailHTML: ({ token }) =>
        `<p><a href="https://yourapp.com/verify?token=${token}">Confirm your email</a></p>`,
    },
    forgotPassword: {
      generateEmailSubject: () => 'Reset your password',
      generateEmailHTML: ({ token }) =>
        `<p><a href="https://yourapp.com/reset-password?token=${token}">Choose a new password</a></p>`,
    },
  },
  fields: [],
};

With your own URL, your front end calls Payload's reset-password or verify operation with the token; the same Payload page says so. Each of these emails is one POST /emails from the key in AGENTISEND_API_KEY, so the key's send budget covers sign-ups and resets together. Give the CMS its own key, and a burst of password resets cannot spend the budget of the key your app sends receipts with.

What comes back when it goes wrong

payload.sendEmail rejects with the refusal itself: read code and fix on the error rather than its stack. Two are common in a new Payload project: domain_not_verified, when defaultFromAddress is on a domain not yet verified, and agent_budget_exceeded, when the CMS key has spent its budget for the period. The error catalogue lists every code.

Next