Authentication Emails

The emails authentication sends, how to change their text, and what happens when sending fails.

Authentication sends the emails below, through the email queue and void/email. Their bodies are React Email components from @kit/email-templates.

This page is part of the Authentication documentation.

What's Sent

EmailWhenLink
Verify your emailSign-up, and "send the link again"/api/auth/verify-email?token=…, valid 30 minutes
Reset your passwordA reset request for an address with an account/api/auth/reset-password/<token>, valid 1 hour, works once
Sign in to … (magic link, when AUTH_MAGIC_LINK is on)"Send Email Link"/api/auth/magic-link/verify?token=…, valid 5 minutes, works once
… is your sign-in code (when AUTH_EMAIL_OTP is on)"Email me a code", "Send a new code"none: a 6-digit code, valid 5 minutes, 3 tries
Your accountSomeone signs up with an address that already has a verified accountSign-in page
Approve the new emailA signed-in user asks to change their email (Profile); sent to the current address, naming the new one/email-change?token=…, a page whose button approves (a POST, so mail scanners approve nothing), valid 30 minutes
Confirm your new emailThe change was approved; sent to the new address/api/auth/verify-email?token=…, valid 30 minutes
Your email was changedThe new address was confirmed; sent to the old addressSign-in page
Your password was changedA signed-in user changed their password (Security); sent to the account's addressSign-in page
A password was added to your accountA signed-in user added a password to an account that had none (Security); sent to the account's addressSign-in page
A sign-in method was addedA provider account was added to an existing user (linked from Security, or a provider sign-in matching a verified email); sent to the account's addressSign-in page

A request for an unknown address sends nothing and shows the same screen. An email change to an address another account owns gets the same reply and the same approval email (so the requester's inbox doesn't tell either); approving it then sends nothing to that address. Emails are sent after the response (waitUntil), so response time doesn't reveal whether an address has an account.

Changing the Text

Strings live in the kit's packages/i18n/src/messages/<locale>/auth.server.json under emails: a server-only file, so they never reach the browser (edit them with the kit_translations_* MCP tools, namespace auth.server; kit updates may change this file, see Managing Translations). The email's language follows the visitor's locale cookie, then their browser languages. {productName} comes from PRODUCT_NAME.

apps/web/config/auth-mailer.server.ts (authMailer) binds createQueuedAuthMailer from @kit/better-auth/mailer, which queues each email with the visitor's locale (locale cookie, then accept-language); the Better Auth options only call the mailer. The email queue (apps/web/queues/emails.ts) renders and sends it: templates authLink and signInCode from createKitEmailTemplates in @kit/email-templates/server (packages/email-templates/src/kit-templates.tsx, bound to the app's translator in apps/web/config/kit-email-templates.server.ts; kit-owned; add your own emails in apps/web/config/email-templates.server.tsx), built from the React Email components in @kit/email-templates (LinkEmail, CodeEmail). Change those to change how an email looks.

Sender

The sender is email.from in apps/web/void.config.ts; sendEmail calls don't pass one. See Setup.

Failures

The mailer never throws: the user sees "check your email" either way and can ask again. If the email can't be queued it logs auth email not queued. The queue retries a send that failed for a passing reason (quota, provider unreachable, unknown outcome) 3 times, 30 seconds apart; any other failure, or the last attempt, logs email not sent with the template, the recipient's domain, the attempt count and the error code, never the link or code. Void queues have no dead-letter queue, so a dropped email is only in the logs. A retried send can arrive twice (there's no idempotencyKey on direct Cloudflare); every kit email carries the same link or code each time, so a duplicate is harmless. Organization invitations go through the same queue (organizationInvitation, queued by @kit/organizations' invitations service); one that can't be queued logs invitation email not queued and stays pending, to resend.

Locally

  • pnpm dev: emails land in Void's dev inbox (the dev server prints its address, http://localhost:5173/__void/inbox?token=…, at startup).
  • pnpm preview and e2e: the queue runs locally, but there's no email sender, so every send logs email not sent (INVALID_FROM or BINDING_MISSING). That's expected. E2E builds the links itself; see Testing.