Emails

Emails

Emails are handled in Payload using the built-in email adapter. This adapter is configured to use SMTP for sending emails. The configuration for the email adapter can be found in the .env file.

Environmental Variables

The following environmental variables are used to configure the email adapter:

SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=
SMTP_FROM_ADDRESS=
SMTP_FROM_NAME=

In theory, this should work with any SMTP server. Please consider their Terms of Service and any limitations they may have on sending emails.

Ben’s live dev server is using using a business-grade provider and can be used for testing email functionality.

Fallback

If no SMTP configuration is provided, Payload will fall back to using the console for emails during development. This means that no actual email will be sent, but the content will be visible in the terminal.

Requesting email verification

Registration creates the account with email_verified: false, stores a random verification token valid for 72 hours, and emails a verification link. The link looks like:

https://[frontend url here]/en/verify-email?token=<64-hex-chars>

To send (or re-send) a verification link to an unverified address, use the request endpoint. It rotates the token, so any previous link stops working. Already-verified addresses get a harmless success message and no mail. Requesting is limited to 3 per email in a 15-minute window.

POST {{baseUrl}}/users/request-email-verification

{
  "email": "[email protected]"
}

To verify a token directly (what the Astro link-handler page calls):

POST {{baseUrl}}/users/verify-email

{
  "token": "<64-hex-chars>"
}

Sending a new link

In this codebase, browser code never calls Payload directly (the session token is httpOnly). Things like this have been mostly run through proxy endpoints within Astro.

The main endpoint for requesting email verification in Astro is /api/auth/request-email-verification which calls /api/users/request-email-verification in payload.

It maps the input email to a user by itself and sets up the tokens for you.

The proxy (frontend/astro/src/pages/api/auth/request-email-verification.ts) maps the Payload response to a redirect, so the page reads the result without any client-side fetch:

Payload status	Redirect	Meaning for the UI
200 sent	?email=…&sent=1	Show “check your inbox”.
200 already verified	/login?verified=1	Address is verified; send them to sign in.
404	?email=…&error=no-account	No account for that email.
429	?email=…&error=ratelimit	Over the 3 per 15-minute period rate limit.