Email

Email is a key part of Better Auth, required for all users regardless of their authentication method. Better Auth provides email and password authentication out of the box, and a lot of utilities to help you manage email verification, password reset, and more.

Email Verification

Email verification is a security feature that ensures users provide a valid email address. It helps prevent spam and abuse by confirming that the email address belongs to the user.

Adding Email Verification to Your App

To enable email verification, you need to pass a function that sends a verification email with a link.

• sendVerificationEmail: This function is triggered when email verification starts. It accepts a data object with the following properties:
  • user: The user object containing the email address.
  • url: The verification URL the user must click to verify their email.
  • token: The verification token used to complete the email verification to be used when implementing a custom verification URL.

and a request object as the second parameter.

import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // your email sending function
 
export const auth = betterAuth({
    emailVerification: {
        sendVerificationEmail: async ({ user, url, token }, request) => {
            await sendEmail({
                to: user.email,
                subject: 'Verify your email address',
                text: `Click the link to verify your email: ${url}`
            })
        }
    }
})

Triggering Email Verification

You can initiate email verification in two ways:

1. During Sign-up

To automatically send a verification email at signup, set emailVerification.sendOnSignUp to true.

import { betterAuth } from 'better-auth';
 
export const auth = betterAuth({
    emailVerification: {
        sendOnSignUp: true
    }
})

This sends a verification email when a user signs up. For social logins, email verification status is read from the SSO.

2. Require Email Verification

If you enable require email verification, users must verify their email before they can log in. And every time a user tries to sign in, sendVerificationEmail is called.

export const auth = betterAuth({
    emailAndPassword: {
        requireEmailVerification: true
    }
})

if a user tries to sign in without verifying their email, you can handle the error and show a message to the user.

await authClient.signIn.emailAndPassword({
    email: "[email protected]",
    password: "password"
}, {
    onError: (ctx) => {
        // Handle the error
        if(ctx.error.status === 403) {
            alert("Please verify your email address")
        }
        //you can also show the original error message
        alert(ctx.error.message)
    }
})

3. Manually

You can also manually trigger email verification by calling sendVerificationEmail.

await authClient.sendVerificationEmail({
    email: "[email protected]",
    callbackURL: "/" // The redirect URL after verification
})

Verifying the Email

If the user clicks the provided verification URL, their email is automatically verified, and they are redirected to the callbackURL.

For manual verification, you can send the user a custom link with the token and call the verifyEmail function.

authClient.verifyEmail({
    query: {
        token: "" // Pass the token here
    }
})

Auto SignIn After Verification

To sign in the user automatically after they successfully verify their email, set the autoSignInAfterVerification option to true:

const auth = betterAuth({
    //...your other options
    emailVerification: {
        autoSignInAfterVerification: true
    }
})

Password Reset Email

Password reset allows users to reset their password if they forget it. Better Auth provides a simple way to implement password reset functionality.

You can enable password reset by passing a function that sends a password reset email with a link.

import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // your email sending function
 
export const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
        sendResetPassword: async ({ user, url, token }, request) => {
            await sendEmail({
                to: user.email,
                subject: 'Reset your password',
                text: `Click the link to reset your password: ${url}`
            })
        }
    }
})

Check out the Email and Password guide for more details on how to implement password reset in your app.