Supported Liquid Syntax for Email Templates

A list of Liquid tags, filters, and common variables supported in email templates.

For an overview of Liquid syntax, read the LiquidJS introduction. It has a brief summary of Liquid’s two kinds of markup:

• Outputs, which output HTML.

  The syntax for outputs is a variable or value and optional list of filters surrounded by {{ and }}. For example, {{ user.name }}.

• Tags, which control template rendering and implement logic.

  The syntax for tags is a tag name and optional arguments surrounded by{% and %}. For example, {% if user_metadata.lang == 'it' %} Ciao! {% endif %}.

This page lists the tags, filters, and variables supported in email templates.

Tags

All email templates support the following Liquid tags:

Category	Tags
Iteration	for, cycle, tablerow
Control flow	if, unless, elsif, else, case
Variable	assign, increment, decrement
File	include, layout
Language	raw, comment

You can view descriptions and examples of Liquid tags on the LiquidJS tags page.

debug tag

To support debugging and development, our custom {% debug %} tag outputs a summary of the template variables available to your template when it was rendered.

Filters

All email templates support the following Liquid filters:

Category	Filters
Math	plus, minus, modulo, times, floor, ceil, round, divided_by, abs, at_least, at_most
String	append, prepend, capitalize, upcase, downcase, strip, lstrip, rstrip, strip_newlines, split, replace, replace_first, remove, remove_first, truncate, truncatewords
HTML/URI	escape, escape_once, url_encode, url_decode, strip_html, newline_to_br
Array	slice, map, sort, sort_natural, first, last, join, reverse, size
Date	date
Misc	default

You can view descriptions and examples of Liquid filters on the LiquidJS filters page.

General variables

The following variables are available to the From Address, Subject, and Message fields in every template (unless otherwise noted).

To use untrusted properties in email templates, escape them with the escape filter (for example, {{ user.name | escape }}).

• The application object, with access to the standard client properties like application.name and application.client_metadata

• request_language language selection for users

• connection.name

• In the MFA enrollment email template, the connection.name variable is not available.

• Tenant-related information defined in Tenant Settings:

  • tenant, which is the raw tenant name
  • friendly_name
  • support_email
  • support_url

• The following user variables:

  • user.email
  • user.email_verified
  • user.picture (untrusted)
  • user.nickname (untrusted)
  • user.given_name (untrusted)
  • user.family_name (untrusted)
  • user.name (untrusted)
  • user.app_metadata, user attributes that can impact a user’s core functionality, such as how an application functions or what the user can access, including their support plan, security roles, and access control groups
  • user.user_metadata (untrusted if containing user-provided information), user attributes that do not impact a user’s core functionality, including user preferences

In the Passwordless OTP email template, only the email property of the user object is available.

• When a user logs in through an Organization, the following additional variables are available:

  • organization.id
  • organization.display_name
  • organization.name
  • organization.metadata
  • organization.branding.logo_url
  • organization.branding.colors.primary
  • organization.branding.colors.page_background

• Multiple custom domains variables:

  • custom_domain.domain, the custom domain name being used (e.g., login.example.com)
  • custom_domain.domain_metadata, the custom domain’s metadata fields (key-value pairs) that you can use to customize email content based on the domain

When using multiple custom domains, Auth0 automatically uses the appropriate custom domain for email links. You can use these variables to customize email content based on which custom domain triggered the email.

Example: Customize email branding based on custom domain metadata:

{% if custom_domain.domain_metadata.brand == "BrandA" %}
  <h1 style="color: #0000FF;">Welcome to Brand A</h1>
{% elsif custom_domain.domain_metadata.brand == "BrandB" %}
  <h1 style="color: #FF0000;">Welcome to Brand B</h1>
{% else %}
  <h1>Welcome</h1>
{% endif %}

Example: Include domain-specific support information:

{% if custom_domain.domain_metadata.support_email %}
  <p>Need help? Contact us at {{ custom_domain.domain_metadata.support_email }}</p>
{% else %}
  <p>Need help? Contact us at {{ support_email }}</p>
{% endif %}

To use custom domains in emails, ensure you have:

1. Configured and verified your custom domains
2. Enabled Use Custom Domain in Emails in Dashboard > Branding > Custom Domains
3. Set a default custom domain if using multiple custom domains

Redirect To variables

In email templates with a Redirect To URL field, only the following three variables are supported:

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

• application.clientID

• application.callback_domain (or its synonym client.callback_domain), which contains the origin of the first URL listed in the application’s Allowed Callback URL list. This is an origin and therefore includes the protocol (like https://) in addition to the domain.

  The callback domain lets you redirect users to a path of the application that triggered the action by using a syntax like {{ application.callback_domain }}/result_page.

Template-specific variables

In addition to the common Liquid variables available to all email templates, the following email templates have additional variables available.

Blocked account email template variables

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

Change password (code) email template variables

• code, the password change code

Change password (link) email template variables

• url, the password reset link

MFA enrollment email template variables

• link, the MFA enrollment link.

Passwordless OTP email template variables

• send, with 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)
• operation, with a value of change_email for a passwordless email change operation

User invitation email template variables

• inviter.name
• roles.id
• roles.name
• roles.description

Verification email (code) template variables

• code, the verification code

Verification email (link) template variables

• url, the verification link