# Authentication Emails

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/emails*

---

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](./overview).

## What's Sent

| Email | When | Link |
|---|---|---|
| Verify your email | Sign-up, and "send the link again" | `/api/auth/verify-email?token=…`, valid 30 minutes |
| Reset your password | A 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 account | Someone signs up with an address that already has a verified account | Sign-in page |
| Approve the new email | A 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 email | The change was approved; sent to the **new** address | `/api/auth/verify-email?token=…`, valid 30 minutes |
| Your email was changed | The new address was confirmed; sent to the **old** address | Sign-in page |
| Your password was changed | A signed-in user changed their password (Security); sent to the account's address | Sign-in page |
| A password was added to your account | A signed-in user added a password to an account that had none (Security); sent to the account's address | Sign-in page |
| A sign-in method was added | A 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 address | Sign-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](../internationalization/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](./setup#email-sender).

## 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](./testing).
