Kernlift

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.read and config.write.

Pick the provider by where your domain and account already live:

ProviderCredentialsSender
ResendOne API keyFrom address, on a domain verified in Resend
Cloudflare EmailAccount ID and API tokenFrom address, on a domain set up for Email Service in Cloudflare
Aliyun DirectMailAccessKey ID and secretSender account created in the DirectMail console; From address is not used

Prepare the email provider

ProviderChoose it for
ResendSend from a verified domain with a sending key
Cloudflare EmailSend using a Cloudflare account and token
Aliyun DirectMailUse 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:

TemplateWhen
email-verificationOn sign-up, when an unverified user tries to sign in while email verification is required, and when a user asks to resend.
password-resetWhen a user requests a password reset. Always sent in English.
contact-routedWhen 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.

src/server/services/example.service.ts
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.

Reference

Next steps