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. In this guide, you'll get a walk through of how to implement token based email verification in your app. To use otp based email verification, check out the OTP Verification guide.

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) => {
            void 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 several 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.

import { betterAuth } from "better-auth";
import { sendEmail } from './email'; // your email sending function

export const auth = betterAuth({
  emailVerification: {
    sendVerificationEmail: async ({ user, url }) => {
      void sendEmail({
        to: user.email,
        subject: "Verify your email address",
        text: `Click the link to verify your email: ${url}`,
      });
    },
    sendOnSignIn: true,
  },
  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.email({
    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.

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

Auto Sign In After Verification

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

import { betterAuth } from "better-auth";

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

Callback before email verification

You can run custom code just before a user's email is marked as verified using the beforeEmailVerification callback. This is useful for validation, pre-checks, or preparing data before the verification is finalized.

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
    emailVerification: {
        async beforeEmailVerification(user, request) {
            // Run pre-verification logic
            console.log(`About to verify ${user.email}`);
        }
    }
})

Callback after successful email verification

You can run custom code immediately after a user verifies their email using the afterEmailVerification callback. This is useful for any side-effects you want to trigger, like granting access to special features or logging the event.

The afterEmailVerification function runs automatically when a user's email is confirmed, receiving the user object and request details so you can perform actions for that specific user.

Here's how you can set it up:

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
    emailVerification: {
        async afterEmailVerification(user, request) {
            // Your custom logic here, e.g., grant access to premium features
            console.log(`${user.email} has been successfully verified!`);
        }
    }
})

Callback on duplicate sign-up attempt

The onExistingUserSignUp callback is triggered when someone tries to sign up with an email that already exists. This is useful for notifying the existing user that someone attempted to register with their email address.

import { betterAuth } from 'better-auth';

export const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
        onExistingUserSignUp: async ({ user }, request) => {
            // Notify the existing user about the sign-up attempt
            console.log(`Someone tried to sign up with ${user.email}`);
        }
    }
})

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) => {
            void 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. Also you can check out the Otp verification guide for how to implement password reset with OTP in your app.