• Home
• Productivity Tips
• Using Liquid for Personalization

Very often we see companies create a number of very similar campaigns, which only vary slightly. This is not the best practice — you’d have to set up (or change) the same messages multiple times.

There’s a better way! Sometimes you’ll need your emails to be a bit smarter than plain-text. That’s when Liquid comes to help: you can use conditions, insert variables, and do many other great things to personalize your campaigns.

What is Liquid?

Liquid is an open-source template language created by Shopify. Here’s the official full-text manual for your reference. In this guide, you’ll find a few key elements and ideas for customizing your campaigns.

How can I make sure that my Liquid tags work properly?

Our message preview feature allows you to test messages using data from any individual user. You can select one one of the names on the right, or find a particular person using the search field. To open the preview window, click "Preview" in the top right corner of the screen.

Property tags provided by Userlist

In Userlist, you can use Liquid tags in message subject, message body, and footer settings. You can even use them in link URLs. Tags are formatted like this: {{tag name}}. Below is a list of tags to use if you want to insert specific properties.

User properties

Company properties

Your account properties

Message Properties

Event Properties

In both campaigns and workflows started by a “User performed custom event” trigger, you can also access the event that caused them to start.

Using conditions

You can hide, show, or customize parts of your messages using conditions (formally called control flow tags in Liquid). Such tags are formatted like this: {% sample tag %}

if

Shows a part of your message only if a certain condition is true. In the following example, we highlight marketing features to marketers only:

1
2
3
{% if user.occupation == 'marketer' %}
  You can use Sparkle.io to instantly transform photos into marketing materials.
{% endif %}

unless

The opposite of if — shows a part of your message only if a certain condition is not met. In the following example, we describe the features to everyone but designers:

1
2
3
{% unless user.occupation == 'designer' %}
  Our features can help you process graphics without an in-house designer.
{% endunless %}

The same result could be achieved using if and != (is not equal to):

1
2
3
{% if user.occupation != 'designer' %}
  Our features can help you process graphics without an in-house designer.
{% endif %}

else

Adds more conditions within an if block. In the following example, we include a specific sentence for marketers, and show a generic sentence otherwise:

1
2
3
4
5
{% if user.occupation == 'marketer' %}
  You can use Sparkle.io to instantly transform photos into marketing materials.
{% else %}
  Sparkle.io is a versatile tool for all kinds of agency roles.
{% endif %}

case/when

Allows you to customize a part of copy based on a variety of values. In the following example, we customize the introduction based on the user’s occupation (marketer, designer, or photographer), and show a generic introduction to everybody else:

1
2
3
4
5
6
7
8
9
10
{% case user.occupation %}
  {% when 'marketer' %}
     Dear marketers,
  {% when 'designer' %}
     Dear designers,
  {% when 'photographer' %}
     Dear photographers,
  {% else %}
     Dear users,
{% endcase %}

If the property doesn’t have a value yet, the result will safely fall back to else.

Logic operators

In the above examples, we’ve been using == (is equal to) to compare values. Below you’ll find other logic operators to use:

Available filters

In addition to the standard filters of Liquid, we offer a couple of filters that are unique to Userlist.

Number formatting

Date calculations

The following examples assume that now is 2021-08-12 10:23:54 UTC.

It is also possible to modify the time by one or multiple dimensions. The following examples assume that now is 2021-08-12 10:23:54 UTC.

If you'd like to show the end of the next month, you can combine the filters.

1
{{ 'now' | advance: months: 1 | end_of_month}}

Assuming that now is 2021-08-12 10:23:54 UTC, this will output 2021-09-30 23:59:59 UTC.

Popular customization formulas

Use a default placeholder

Use a placeholder if the property hasn’t been specified. The following example will say friend if there’s no first name available:

1
{{user.first_name | default: "friend"}}

Capitalize property values

The following example capitalizes the first_name property with the capitalize filter:

1
{{user.first_name | capitalize}}

Combined with the previous placeholder formula, it would look like this:

1
{{user.first_name | capitalize | default: "friend"}}

The default "friend" value won’t be capitalized because capitalize only applies to everything on the left (it’s called “pipeline” syntax). Similar to capitalize, you can also use upcase and downcase to convert the value to uppercase or lowercase.

Add text before or after a property

For this, use the following filters:

• prepend — adds text in the beginning
• apppend — adds text in the end

In the example below, we're adding a sign @ before the recipient's handle:

1
Hey {{user.handle | capitalize | prepend: "@"}}

If their handle is catwoman, the result will be Hey @Catwoman.

Show the first name

If you only have full_name of your users available, you can extract their first name (the first word) with the following formula:

1
{{user.full_name | split: " " | first}}

Format date & time

To make date & time properties readable, you should customize their format when inserting them into your messages. Here are some common examples:

You can find the full list of date & time placeholders in this documentation.

Show how many days are left in a trial

Here’s an example showing how many days are left in user’s trial:

1
Thanks for being with us! You have {% assign current_date = 'now' | date: '%s' %}{% assign future_date = user.trial_expiration %}{{future_date | minus: current_date | divided_by: 86400}} days left in your trial.

We’re calculating the difference between two dates and dividing it by 86400 (number of seconds in a day). The result will be rounded down.

Humanize numbers

You can user the following formula to display integers as words (e.g. “two” or “fifty five”):

1
Congrats, you have taken {{user.recent_photos | humanize}} photos today!