Liquid Templating in Messages

Liquid templating in messages allows for greater flexibility to create dynamic and powerful messages for your customers.

Mixpanel has two options for templating and personalization, advanced templating through Liquid, and a Mixpanel custom templating language. You can choose one or the other as you compose email messages.

Select the checkbox marked Use advanced personalization at the bottom of the message form to use Liquid formatting.


This functionality is currently only available in email messages.

Liquid is an open source templating language created by Shopify. Liquid templating language is usable in its officially documented form with only a few caveats. The official documentation can be found here.

Liquid code has three elements: objects, tags and filters.

  • Objects: typically variable names. Liquid objects contain attributes to output dynamic content in your message. For example, you can use variables stored in your user profiles. Objects are always enclosed within double curly braces.
    For example:
{{ user["$name"] }}
  • Tags: create the logic and control flow for templates. Tags are denoted by curly braces and percent signs: {% and %}. They produce no visible text.
    For example:
{% if user["$name"] %}
Hi {{ user["$name"] }}
{% endif %}  
  • Filters: change the output of a Liquid object. Filters are used within an output (in curly braces) and are separated by a |. View all Liquid filters here.
    For example:
{{ "" | append: user["recommended_product_id"] }}

Common Use-Cases

Here are several helpful common use-cases for Liquid syntax.

Conditional Statements

  • Language localization: Create a single email with different text for each language, rather than creating separate emails for each.
    For example:
{% if user["language"] == "Spanish" %}
Hola {{ user["$name"] }}!
{% elsif user["language"] == "French" %}
Bonjour {{ user["$name"] }}!
{% else %}
Hi {{ user["$name"] }}!
{% endif %}
  • Product recommendations: Send product recommendations based on other products the customer already has.
    For example:
{%if user["asset_type"]=="Bitcoin" 
or user["asset_type"]=="Ether"%}
Have you considered our latest Litecoin offering here?


  • Recommendation lists: Send a list of recommendations to a user based on other products they have looked at.
    For example:
You may be interested in some of these products
{% for products in user["products_list"] %}
{{ products }}
{% endfor %}


  • User name capitalization: 
Hi {{ user["name"]|capitalize }}
  • Appending custom text:
{% assign campaign_name = "/index.html" %}
{{ ""| append: campaign_name }}
  • Time formatting: Pass the special object "now" to get the current time and use that in your emails to automatically update copyrights as the year changes.
    For example:
Mixpanel © {{ "now" | date: "%Y" }}


There are several instances in which the format of Mixpanel's templates differs from Liquid. This guide will clarify those differences.

User Property Namespacing

Mixpanel expects all variable substitution for user properties to be escaped and placed under the namespace user. For example, if a user had the properties $name and language, you would express it like the following:

{% if user["language"] == "Spanish" %}
Hola {{user["$name"]}}!
{% elsif user["language"] == "French" %}
Bonjour {{user["$name"]}}!
{% else %}
Hi {{user["$name"]}}!
{% endif %}

Restricted User Property Characters

User properties containing the characters " or } will not be properly substituted and may result in a failure to send messages. Note that these characters are still viable in Mixpanel’s custom templating language if properly escaped.

For example, if you had a user property called ab}}cde, Mixpanel’s custom templating would allow you to express that as {{${ab\}\}cde}}} but this is not expressible in the Liquid templating format.

Liquid only supports the standard double quote character ". Several text editors may swap this with open and close double quote characters such as “...”. These will cause Liquid to fail.

Differences Between Mixpanel and Liquid Syntax

The braces to declare variables and conditionals are the same between Mixpanel and Liquid; however, the contents of those braces will differ slightly.

Variable Substitution

In Mixpanel syntax, it isn’t required to escape all variables, although many will need to be anyway. In Liquid, all variables (representing user properties) are expected to be escaped and namespaced under user. This means that, while the property $name in Mixpanel would be substituted in the following manner:


it would be represented in Liquid syntax with the following:


Conditionals/Control Flows

The control flow syntax is identical between both Mixpanel syntax and Liquid syntax. Liquid syntax provides additional functionality in the form of comparisons and elsif expressions. This means that instead of being limited to something like the following, assuming any user with a language is French:

{% if ${language} %}
{% else %}
{% endif %}

In Liquid, an email could have more options:

{% if user["language"] == "Spanish" %}
Hola {{user["$name"]}}!
{% elsif user["language"] == "French" %}
Bonjour {{user["$name"]}}!
{% else %}
Hi {{user["$name"]}}!
{% endif %}


Mixpanel currently supports one type of filter: fallback. This filter provides a default value if the user property is empty. An example of this would be the following:

Hi {{${$name}|fallback: "new user" }}!

This functionality also exists in Liquid, however, the keyword is instead default. Given that difference, the same template could be produced with the following in Liquid:

Hi {{user["$name"] | default: "new user"}}!

Liquid also supports many other filters that are shown here.

Is this article helpful?
3 out of 4 found this helpful



Article is closed for comments.