Customize Email Handling

Our default email flow can address the requirements of most applications. Sometimes, however, you may require more flexibility, such as when implementing:

  • localization

  • custom Redirect To URLs based on user or tenant

  • different email templates per application or tenant

The Auth0 Management API provides endpoints to help you manage your email flow to control when and how emails are sent. If necessary, you can also implement your own Custom Email endpoints and use the Auth0 Management API endpoints to help manage the rest of the flow.

Prerequisites

Before you begin, you must disable automatic emails:

  1. Navigate to Auth0 Dashboard > Branding > Email Templates.

  2. For Template, select Verification Email (using Link).

  3. Toggle the switch to disable the Status.

  4. Repeat for the Welcome Email template.

Verification emails

A verification email should be sent to every user for which the email_verified property is false. Typically, these are users in database connections or users authenticating with social providers that do not validate email addresses upon new user registration.

Send verification email with Management API

The Send an email address verification email endpoint sends the user an email prompting them to verify their email address.

Send verification email with Rules

Using Auth0 Rules, you can call your API when a user logs in for the first time with an email address that has not been verified. After calling your API, add a flag to the user's profile metadata that indicates that the verification email has been sent:

function (user, context, callback) {

  const request = require('request');

  user.user_metadata = user.user_metadata || {};
  if (user.email_verified || user.user_metadata.verification_email_sent) {
    return callback(null, user, context);
  }

  request.post({
    url: 'https://yourapi.yourcompany.com/mail/verification',
    json: {
      user: user,
      context: context,
      secretToken: configuration.MY_SECRET_TOKEN,
    },
    timeout: 5000
  }, function(err, response, body){
    if (err)
      return callback(new Error(err));

    // Email sent flag persisted in the user's profile.
    user.user_metadata.verification_email_sent = true;
    auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
      .then(function() {
        callback(null, user, context);
      })
      .catch(function(err) {
        callback(err);
      });
    return callback(null, user, context);
  });
}

Require verified email for login

You can require users to verify their email before logging in with a rule:

function (user, context, callback) {
  if (!user.email_verified) {
    return callback(new UnauthorizedError('Please verify your email before logging in.'));
  } else {
    return callback(null, user, context);
  }
}

Custom redirects

A custom redirect is useful when you want to direct users to certain URLs based on user attributes or on the tenant. The Auth0 Management API provides a Create Email Verification Ticket endpoint that generates the verification link for each user. This endpoint allows you to specify the result_url to which users will be redirected after they have validated their email address by clicking the link in the verification email.

We recommend AllowList the URL in the Auth0 Dashboard. For details, see Add Addresses to AllowList.

Welcome emails

A welcome email is sent to users once they have verified their email address.

Send welcome email using your own API

Using a rule, you can call your API to send a welcome email only if the user's email address has been verified and the email has not been sent previously.

function (user, context, callback) {

  const request = require('request');

  if (!user.email_verified || user.welcome_email_sent) {
    return callback(null, user, context);
  }

  request.post({
    url: 'https://yourapi.yourcompany.com/mail/welcome',
    json: {
      user: user,
      context: context,
      secretToken: configuration.MY_SECRET_TOKEN,
    },
    timeout: 5000
  }, function(err, response, body){
    if (err)
      return callback(new Error(err));

    // Email sent flag persisted in the user's profile.
    user.app_metadata.welcome_email_sent = true;
    return callback(null, user, context);
  });
}

Change password confirmation emails

To handle password change requests, you will need to host a form to capture the user's new password, and post it to the Create Password Change Ticket endpoint in the new_password parameter. Calling this endpoint will generate a Change Password Confirmation link. With it, you can send the user an email containing the link. When the user clicks the link, they can update their password.

Alternatively, if you invoke the endpoint without specifying the new_password parameter, the link in the email will redirect the user to a page prompting them to set a new password.

Manage Email Flow Change Password Confirmation Email Flow Diagram

Learn more