Use Liquid Syntax in Email Templates

When using the Email Templates available on the Auth0 dashboard, you have the option of using the Liquid template language to select the appropriate data and formatting your emails. Liquid is an open-source templating language that extends the functionality of HTML that you can use to dynamically generate your emails to contain varying information. To learn more, read Liquid for Designers on Github.

Using Liquid, you can structure the Subject of your emails to display the appropriate application name, rather than hardcoding a particular value:

We are {{application.name}}!

HTML with Liquid syntax is supported in every field (except URL Lifetime) on the Verification, Change Password Confirmation, and Blocked Account email templates. For more information on supported output attributes and their usage, see Customize Email Templates.

There are two types of markup in Liquid: output and tag.

Output markup

Output markup resolves to text and is surrounded by two pairs of matching curly braces:

Hello {{ name }}!

You can further customize the appearance of the output by using filters, which are simple methods. For example, the upcase filter will convert the text which is passed to the filter to uppercase:

Hello {{ name | upcase }}!

Multiple filters are separated by | and are processed from left to right, applying the subsequent filter to the result of the previous one. The template will render the final result.

The following filters are supported:

Filter Description Example
append Append a string {{ 'foo' | append:'bar' }} #=> 'foobar'
capitalize Capitalize words in the input sentence {{ "my great title" | capitalize }} #=> My great title
date Reformat a date (syntax reference)
default Returns the given variable unless it is null or the empty string, when it will return the given value {{ undefined_variable | default: "Default value" }} #=> "Default value"
divided_by Integer division {{ 10 | divided_by:3 }} #=> 3
downcase Convert an input string to lowercase, {{ "Parker Moore" | downcase }} #=> parker moore
escape HTML escape a string {{ "Have you read 'James & the Giant Peach'?" | escape }} #=> Have you read 'James & the Giant Peach'?
escape_once Returns an escaped version of HTML without affecting existing escaped entities {{ "1 < 2 &amp; 3" | escape_once }} #=> 1 &lt; 2 &amp; 3
first Get the first element of the passed in array
join Join elements of the array with certain character between them
last Get the last element of the passed in array
map Map/collect an array on a given property
minus Subtraction {{ 4 | minus:2 }} #=> 2
modulo Remainder {{ 3 | modulo:2 }} #=> 1
newline_to_br Replace each newline (\n) with HTML break
plus Addition {{ '1' | plus:'1' }} #=> 2, {{ 1 | plus:1 }} #=> 2
prepend Prepend a string {{ 'bar' | prepend:'foo' }} #=> 'foobar'
remove Remove each occurrence {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar'
remove_first Remove the first occurrence {{ 'barbar' | remove_first:'bar' }} #=> 'bar'
replace Replace each occurrence {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar'
replace_first Replace the first occurrence {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar'
round Rounds input to the nearest integer or specified number of decimals {{ 4.5612 | round: 2 }} #=> 4.56
size Return the size of an array or string {{ "Ground control to Major Tom." | size }} #=> 28
sort Sort elements of the array
split Split a string on a matching pattern {{ "a~b" | split:"~" }} #=> ['a','b']
strip_html Strip HTML from string {{ "How <em>are</em> you?" | strip_html }} #=> How are you?
strip_newlines Strip all newlines (\n) from string
times Multiplication {{ 5 | times:4 }} #=> 20
truncate Truncate a string down to x characters. It also accepts a second parameter that will append to the string {{ 'foobarfoobar' | truncate: 5, '.' }} #=> 'foob.'
truncatewords Truncate a string down to x words
upcase Convert an input string to uppercase {{ "Parker Moore" | upcase }} #=> PARKER MOORE

Tag markup

Tag markup does not resolve to text and is surrounded by a pair of matched curly braces and percent signs:

{% this does not resolve to text %}

Tags are typically used to apply logic to your template. Using the Liquid supported tags, you can have one template meet several needs.

You could use tags to execute if / else statements to have a single template send out emails in multiple languages.

For example:

{% if user.user_metadata.lang == 'en' %} [email body in English] {% elsif user.user_metadata.lang == 'de' %} [email body in German] {% endif %}

If you need to use additional conditions, consider using a case statement. To learn more about case statements, see Liquid for Designers on Github.

Tag comments

Any content between {% comment %} and {% endcomment %} tags will not be rendered.

This will be seen. {% comment %} This will not be seen. {% endcomment %}

Tag raw

To temporarily disable processing of Liquid markup, use {% raw %} and {% endraw %}. This is useful if you are using syntax that conflicts with Liquid.

For example, you can escape the following Mustache.js line as follows:

{% raw %} var clients = "Clients:<ul>{{#client}}<li>{{fn}} {{ln}}" + {{phone}}</li>{{/client}}</ul>"; {% endraw %}

Debug 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.

Learn more