Standard verified email change
A signed-in user replaces an old mailbox with a new one after proving control of the new address.
Better Auth · Module
changeEmail
Better Auth’s changeEmail feature lets a user request a new email address. Enable it server-side, configure verification delivery, and start the flow with the client’s changeEmail method.
How it works
Enable the feature on the server and configure email verification delivery. The client then submits the replacement address; Better Auth sends verification to that address and changes the account only after verification, unless the documented unverified-current-email option permits an immediate update.
Syntax
await authClient.changeEmail({ newEmail, callbackURL });Parameters
| Name | Type | Description |
|---|---|---|
newEmail | string | Replacement email address submitted for the change request. |
callbackURL | string | Destination to use after the verification step completes. |
Returns
The page documents the client call as an asynchronous request but does not specify a return shape.
Key points
- Turn on the server-side feature under the
userconfiguration before exposing the client flow. - The enabling switch is a boolean named
enabledinsideuser.changeEmail. - The normal flow delivers verification to the replacement address.
- Verification gates persistence of the new address.
- A confirmation callback can add approval from the existing address before new-address verification.
Common mistakes
- The feature must be explicitly enabled before the client method can be used.
- Email verification delivery must be configured for the standard verification flow.
- With immediate updates disabled, an unverified current address does not bypass verification.
Example: Request an email change
import { authClient } from "@/lib/auth-client";
await authClient.changeEmail({
newEmail: "new-email@email.com",
callbackURL: "/dashboard",
});Starts the email-change flow and redirects to the dashboard after verification.
When to use it
Two-stage email-change approval
An application requires approval from the existing mailbox before sending verification to the replacement address.
Unverified-current-email update
A system permits an immediate update when the existing address has not been verified.
Interview questions
QHow is the standard email-change flow configured?
Enable user.changeEmail.enabled on the server, configure emailVerification.sendVerificationEmail, and call authClient.changeEmail with newEmail. The address changes after the new address is verified.
Follow-up: How can the current address approve the request first? Provide sendChangeEmailConfirmation; it sends confirmation to the current email before sending verification to the new one.
QWhere is the verification email sent, and when is the email updated?
The default verification message goes to the new email address. The account email is updated only after the recipient verifies that address.
Follow-up: What option changes behavior for an unverified current address? Set updateEmailWithoutVerification to true to allow an immediate update in that documented case.
QWhat does the client call do?
The client method accepts newEmail and may accept callbackURL, which is used for redirecting after verification. The method initiates the process rather than directly changing the stored address.
Follow-up: What security enhancement can be added before the new-address message? Implement sendChangeEmailConfirmation so the current address must approve the change.
Related
user.changeEmail.enableduser.changeEmail.updateEmailWithoutVerificationemailVerification.sendVerificationEmailsendChangeEmailConfirmationemailOtp.requestEmailChange