Liquid Templating in Messages

The Messaging and Mobile A/B testing features are not available for purchase and will be deprecated from the product on January 1st, 2022. Read more information on the Mixpanel blog.

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 in email messages, advanced templating through Liquid, and a Mixpanel custom templating language. SMS messages only use Liquid Templating.

This functionality is available in email messages, SMS messages, and push notifications

Liquid in Email Messages

Select the checkbox marked Advanced templating (liquid) at the bottom of the message form to use Liquid formatting.


Liquid in SMS Messages

SMS messages use Liquid templating in the message body automatically.


Liquid in Push Messages

Select the checkbox marked Use liquid templating at the top of the message builder to use Liquid formatting. Click Show Advanced at the bottom to add custom data.


You can add Liquid templating in the preview phone screen or the Custom Data box.  


Templating Language

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 message with different text for each language, rather than creating separate messages 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 messages 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 Profile Property Namespacing

Mixpanel expects all variable substitution for user profile 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 Profile Property Characters

User profile 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 profile 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.

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 profile 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, a message could have more options:

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


Did this answer your question?



Article is closed for comments.