Docs

Provision: User Stores

Customizing Your Emails

You must setup your own email provider using a third-party service (Amazon SES, Mandrill or SendGrid) or a custom provider to be able to customize your emails.

Auth0 provides an Emails dashboard that allows you to customize your HTML-based emails, including templating with some contextual attributes using Liquid syntax. This can include references to the context of the current application or user.

Only one template can be used for each template type (for example, only one template for verify emails).

At this time, Auth0 does not support plaintext/text-based emails.

Video transcript

Configuring email templates

You can customize the From Address, the Subject, and the Message body for each email template. You can use Liquid Syntax to dynamically generate content, with access to a number of contextual variables that will be replaced with the relevant values when rendering the email messages.

Up next

Common variables

You can access the following common variables when using Liquid Syntax in the From Address, Subject and Message fields:

  • The application object, with access to the standard client properties like
    • application.name
    • application.clientID
  • connection.name (except in the Multi-factor Enrollment Email)
  • The user object, with access to the following properties:
    • user.email
    • user.email_verified
    • user.picture
    • user.nickname
    • user.given_name
    • user.family_name
    • user.app_metadata - stores information (such as a user's support plan, security roles, or access control groups) that can impact a user's core functionality, such as how an application functions or what the user can access.
    • user.user_metadata - stores user attributes (such as user preferences) that do not impact a user's core functionality.
  • Tenant-related information (defined in the Tenant Settings):
    • tenant - the raw tenant name
    • friendly_name
    • support_email
    • support_url

Variables are referenced using the {{ variable_name }} syntax in Liquid. E.g.:

Note that the attributes available for the user object will depend on the type of connection being used.

Individual email templates define additional variables that are appropriate for the specific template. Be sure to check out the individual templates descriptions below.

For those emails where the user needs to follow a link to take action, you can also configure the URL Lifetime and Redirect To URL destination after the action is completed. Liquid Syntax is also supported in the Redirect To URL field, but only two variables are supported:

  • application.name
  • application.callback_domain

See Configuring the Redirect To URL for more details.

Previous video

Configuring the From Address

Users will see the sender's address in the From Address field when receiving an email from Auth0. If you do not configure a From Address for your emails your emails will be sent from the email address of the first owner of your Auth0 account.

For security purposes, you may not send customized emails from any @auth0.com address. If you are a Private Cloud user, you may configure a similar domain blacklist.

The From Address field supports all the common variables for templates, but these are the most commonly used:

  • application.name
  • friendly_name (for the tenant's defined friendly name)

You can use these variables to set the display name of the From Address to something that relates to the application for which the user signed up. For example, the field could display {{ application.name }} <support@fabrikamcorp.com>, as opposed to simply <support@fabrikamcorp.com>.

You must add the Sender Policy Framework (SPF) and DomainKeys Identified Mail (DKIM) DNS records to your domain's zone file to allow Auth0 to send digitally-signed emails on your behalf. Without these records, the emails may end up in your users' junkmail folders. Additionally, your users may see the following as the From Address:

SPF Configuration

You can configure the SPF by adding a TXT record to your domain's zone file. You should set the host name to @, or leave it empty, depending on the provider. The value of the record should look something like the following.

If you already have an SPF record you can simply add include:spf.mandrillapp.com to the existing record.

DKIM Configuration

The DKIM configuration is configured by adding a TXT record to your domain's zone file. This domain should be the one you use to send emails. For example if you are using Mandrill you would set the host name for this record to:

and the value to:

Configuring the Subject

The Subject field supports all the common variables for templates, including:

  • application.name
  • user.email (and other properties of the user object)

If the Subject field is empty, Auth0 will auto-populate this text depending on what type of email you are sending. For example, one subject line might be "Verify your email."

Configuring the URL Lifetime

The Verification Email, Reset Email and Blocked Account Email contain links which allow users to verify their email address when signing up, confirm their password change, or unblock a blocked account respectively.

You can modify the lifetime of this link for security purposes. By default, the lifetime is 432,000 seconds (five days).

If users click on an expired link and a Redirect To URL is configured, they will be redirected to the configured Redirect To URL. The following text will be appended to the query string:

Configuring the Redirect To URL

The Redirect To URL is an optional destination to redirect the user to after the relevant action (verify account, reset password, unblock account) was performed.

Only the following two variables are available on the Redirect To URL:

  • application.name (or its synonym client.name)
  • application.callback_domain (or its synonym client.callback_domain)

The application.callback_domain variable will contain the domain of the first URL listed in the application's Allowed Callback URL list. This lets you redirect users to a path of the application that triggered the action by using a syntax like this:

If your application has multiple Allowed Callback URLs configured, Auth0 will use the first URL listed.

Dynamic Redirect To URLs

You can set up a different Redirect To URLs based on your application name. For example:

Because the application name is encoded for security, you should always use an encoded value (especially if your application name contains a character that changes once encoded). For example, you'll want to use My%20App instead of My App.

For some single-page apps, the redirect to url can sometimes contain a hash that may be removed. This results in the redirect To url not working as expected. For more information, see: Single-Page App Email Redirect Issue.

Configuring the Message Body

Message bodies have HTML content, and Liquid syntax is the currently supported templating syntax to use. You can use all the common variables plus variables defined in each individual template.

Multilingual Email Templates

You can use Liquid syntax along with properties from the user object to alter the content based on the user preferred language. For example:

Debugging Liquid Template Variables

To assist your template development, we've added a custom {% debug %} liquid tag, which outputs a summary of the template variables available to your template when it was rendered. Remember to remove this tag from any "live" templates.

Using Markdown Syntax

Use of Markdown in email templates has been deprecated, so you will no longer be able to add new Markdown formatting. If you have an existing template in Markdown, you will be able to toggle from Markdown to Liquid, but changing this setting will result in you losing any existing Markdown, as well as the ability to use Markdown.

The use of Markdown in email templating has been deprecated, and is only available for templates which were already using Markdown as the templating syntax. The Markdown syntax uses a @@variable@@ format for variable substitution. The available variables are similar to those mentioned above for Liquid syntax.

For example, you can refer to a user in the template as follows:

Individual Templates Descriptions

Verification Email

If you turn on the Verification Email, users who sign up on a database connection will receive a message asking to confirm their email address by clicking on a URL included in the message.

In addition to the common variables available for all email templates, the Verification Email provides the url variable that refers to the URL that the user will have to click. You will use it in the Message field to create a link that the user can follow, as in this example:

Redirect To Results for the Verification Email Template

You can configure a Redirect To URL to send the users to after the email verification action was attempted. When redirecting, Auth0 will include the following parameters:

  • email indicating the email of the user
  • success with value true or false indicating whether the email verification was successful
  • message with an additional description of the outcome. Some possible values are:
    • Your email was verified. You can continue using the application. (with success=true)
    • This URL can be used only once (with success=false)
    • Access expired. (with success=false)
    • User account does not exist or verification code is invalid. (with success=false)
    • This account is already verified. (with success=false)

The target URL handler should be prepared to gracefully handle other possible messages as well.

Welcome Email

Once a user verifies their email address, they will receive a Welcome Email. If you turn off the Verification Email feature, the Welcome Email will be sent to the user when they sign-up (or login for the first time).

Reset Email

If a user requests a password change, they will receive a Reset Email that contains a URL link. When the user clicks on the link, a Password Reset screen will be presented to enter the new password.

In addition to the common variables available for all email templates, the Reset Email has the url variable that refers to the URL that the user will have to click. You will use it in the Message field to create a link that the user can follow, as in this example:

Redirect To Results for the Reset Email Template

You can configure a Redirect To URL to send the users to after the password change action was attempted. When redirecting, Auth0 will include the following parameters:

  • email indicating the email of the user
  • success with value true or false indicating whether the password change was successful
  • message with an additional description of the outcome. Some possible values are:
    • You can now login to the application with the new password. (with success=true)
    • This URL can be used only once (with success=false)
    • Access expired. (with success=false)
    • The operation cannot be completed. Please try again. (with success=false)

The target URL handler should be prepared to gracefully handle other possible messages as well.

Blocked Account Email

If a user attempts to login ten or more times unsuccessfully from the same IP address, the user account will be locked and they will receive a Blocked Account email. Once the user receives this email, they will not be able to login from that IP address again until they click on the link contained in the email.

If the user successfully logs in before they exhaust their ten allowed attempts, the counter is reset.

In addition to the common variables available for all email templates, the following ones are available in the Blocked Account Email template:

  • user.source_ip
  • user.city
  • user.country

This template also provides the url variable that should be used to create the link that the user needs to follow. E.g.:

Redirect To Results for the Blocked Account Email Template

You can configure a Redirect To URL to send the users to after the account unblocking action was attempted. When redirecting, Auth0 will include the following parameters:

  • email indicating the email of the user
  • success with value true or false indicating whether the account unblocking was successful
  • message with an additional description of the outcome. Some possible values are:
    • Your account has been unblocked. (with success=true)
    • This URL can be used only once (with success=false)
    • Access expired. (with success=false)

The target URL handler should be prepared to gracefully handle other possible messages as well.

Password Breach Alert Email

This email type is sent whenever Auth0 detects that the user is trying to access the application using a password that has been leaked by a third party. These emails are only set after enabling Breached Password Detection in the Anomaly Detection section of the dashboard.

Learn more about Breached Password Detection

Multi-factor Authentication Enrollment Email

This email will be generated when an multi-factor authentication enrollment invitation is sent. The message will contain a link that, when visited, will show the MFA enrollment experience.

Besides the common variables available for all email templates, the link variable is available in this email type, containing the URL that you will use to construct the link for this action, as in this example:

Do note that, unlike other email templates, the correct variable name is link and not url. Also, the connection.name variable is not available on this email template type.

Verification Code for Email MFA

This email will be generated when you use email as a MFA method and request a verification code to be sent.

In addition to the common variables available, the template provides a code variable to render the code used for MFA verification. E.g.:

Passwordless Email

Unlike the previous email templates types, this email template is not configured from the Email Templates section. Instead, it's part of the settings for the Email Passwordless Connection.

The Passwordless Email is sent when a passwordless access is requested, either by code (the user receives a code that types in the application) or by a link (the user clicks on a link and is taken directly to the application).

You can use all the common variables available in all templates, plus the following variables defined specifically for the Passwordless Email template:

  • send, which will contain a value of link, link_ios, link_android or code depending on the type of passwordless email requested.
  • code with the one-time-use code to access the application
  • link with the link that can be clicked by the user to gain access to the application (only for link-type passwordless emails)
  • request_language will have the language code of the user request, if available
  • operation, which will be change_email if this is a passwordless email change operation.

The default template uses the above variables to do something like this:

Note that in the Passwordless Email template only the email property of the user object is available.