Send transactional email
Verification, password reset and your own product emails are delivered through Resend, Cloudflare Email Service or Aliyun DirectMail from templates you can edit.
Email is sent from templates through one active provider. Every attempt, sent or not, is written to a delivery log. Set it up before launch. Without a provider, users cannot receive verification or password reset mail.
Before you begin
- A sending domain verified with the provider (SPF, DKIM and similar DNS records). Mail from an unverified domain is rejected.
- The provider's credentials.
- An admin account with
config.readandconfig.write.
Pick the provider by where your domain and account already live:
| Provider | Credentials | Sender |
|---|---|---|
| Resend | One API key | From address, on a domain verified in Resend |
| Cloudflare Email | Account ID and API token | From address, on a domain set up for Email Service in Cloudflare |
| Aliyun DirectMail | AccessKey ID and secret | Sender account created in the DirectMail console; From address is not used |
Prepare the email provider
| Provider | Choose it for |
|---|---|
| Resend | Send from a verified domain with a sending key |
| Cloudflare Email | Send using a Cloudflare account and token |
| Aliyun DirectMail | Use a regional DirectMail sender account |
Connect the provider
Open Email Config
Go to Settings → Email Config (/admin/config/email). The cards at the top list Resend, Cloudflare Email and Aliyun DirectMail; each shows Ready when its credentials are saved, or Missing, and the sending provider is marked Active. Click the card you want.
Set the sender
Under Delivery, fill in From address (for Resend and Cloudflare), for example Acme <noreply@mail.example.com>, and Contact notification to, the inbox that receives /contact form messages. A blank field keeps its current value.
Paste the credentials
Under Credentials, fill in the fields for the selected provider:
Use the field mapping in your provider’s guide above.
Secret fields come back empty after saving; a blank field keeps the stored value.
Activate and save
Tick Set as active email provider and click Save provider. The card shows Active, and the Runtime panel shows the provider and sender.
The effect of saving depends on the checkbox. Ticked, this card's provider becomes the active one. Unticked on the active provider's card, email sending is turned off. Unticked on another card, only that provider's settings are saved. The line under the box reads Active provider: … or Email sending is off: no active provider.
Before a provider is configured
Nothing is sent, and each attempt is logged as not_configured. Sign-up still works, but while Email verification is on, unverified users cannot sign in. /setup lists Email delivery as required until a provider is active.
Know which emails are sent for you
These templates are sent without any code from you:
| Template | When |
|---|---|
email-verification | On sign-up, when an unverified user tries to sign in while email verification is required, and when a user asks to resend. |
password-reset | When a user requests a password reset. Always sent in English. |
contact-routed | When someone submits the contact form; sent to Contact notification to. |
The template set also includes registration-success, newsletter-welcome, billing-receipt, payment-success, subscription-renewal, subscription-canceled, payment-failed, invoice-ready and security-alert. Nothing sends these automatically; send them from your own code.
Edit a template
Open the templates
Open /admin/email/templates, part of the Email area in the Settings group. Each template appears once per locale under Template configuration, with its variables listed under the key.
Change the content
Change the subject, Text body or HTML body. Use {{name}} placeholders for variables; values are HTML-escaped when sent.
Save and preview
Click Save template; Template saved. confirms it and the variable list is rebuilt from the placeholders. Then open /admin/email/preview, pick the template and click Render preview. The preview uses the same layout as real delivery.
Send an email from your code
Call the email service with a template key, recipient, locale and the template's variables.
import { sendEmailTest } from "@/server/services/email-notifications.service";
const delivery = await sendEmailTest({
templateKey: "payment-success",
to: user.email,
locale: "en",
variables: {
name: user.name,
planName: "Pro",
amount: "$29.00",
orderId: order.id,
receiptUrl: receiptUrl,
},
});
if (delivery.status !== "sent") {
console.warn("Email not sent", delivery.status, delivery.errorMessage);
}The call returns the delivery log row, with status sent, failed or not_configured. It throws only when the template does not exist. If any variable the template uses is missing, nothing is sent and the row is failed with Missing template variables: ....
Verify
Send a test email
Open /admin/email/test; the header shows Provider ready. Choose a Template and Locale, enter your address as Recipient, give every variable a value in Variables JSON, and click Send test email. The form reports Email delivery recorded: and the result.
Check delivery
The message arrives, /admin/email/deliveries lists it as sent, and /auth/forgot-password sends a reset link to an existing account.
pnpm validate:email checks templates, previews, logs and provider wiring. EXTERNAL_VALIDATE_EMAIL_TO=you@example.com pnpm validate:external sends a real password-reset email.
Troubleshooting
Deliveries show not_configured
The active provider is missing a credential, or email is off. Resend needs an API key; Cloudflare needs account ID and API token; Aliyun needs AccessKey ID, secret and sender account.
Email stopped after saving a provider card
The active provider's card was saved with Set as active email provider unticked. Open that card, tick the box and click Save provider.
A delivery is failed with a sender or domain error
The provider rejected the sender. Verify the domain with the provider and make sure From address (or the Aliyun Sender account) is on it.
"Email template not found"
No template exists for that key and locale. Run pnpm db:seed-baseline on a fresh database.