Personalizing content for your contacts can increase engagement with your website and email campaigns. You can personalize your emails, chat bots, chat prompts, conversation snippets and forms with any contact property or custom property.
In order for personalization tags to show a value for a contact, the contact must have a contact record in your Gist workspace and have a known value for the property used as the tag.
Add personalization to your content
This guide explains how Personalization or Liquid tags work and provides a summary of the most commonly used Liquid tags and filters for email, with examples of how to use them. You can also find a list of Gist-specific Liquid tags that make personalizing email that bit easier.
How does it work?
The static elements of an email are written in HTML, and the dynamic elements are written using Liquid tags. The Liquid tags act as placeholders: just before the message is sent to the recipient, the Liquid tags, within your email content, are replaced and interpreted using the contact properties tracked in your Gist workspace.
When using Liquid tags, you should always review the output using the preview and test features within Gist before activating your campaign.
Basic contact properties
To insert a default or custom property directly into an email, just enter the word subscriber followed by the property name, and are denoted by double curly braces: {{ subscriber.PROPERTY_NAME }}. - where you’d like that property to appear in your email.
For example, if you want to include the first name within your email, you'll want to include the tag that references that property. In this case,
{{ subscriber.first_name }}
As you can see, anything you've included as a contact property should start with subscriber.
before your property name. If you've got country
, for example, it'd be {{ subscriber.country }}
Filters and tags
Filters and tags make up the foundations of Liquid, and there are a number of them that you can use. In the first-name example, if you wanted to make sure it was capitalized, add a capitalize
filter to the tag:
{{ subscriber.first_name | capitalize }}
If the field was full_name
and you wanted to include only the first word/name, you could use:
{{ subscriber.full_name | split: " " | first }}
Fallbacks
If only a subset of your contacts have the specific property you want to include, you'll want to only use that tag for matching contacts and set up a fallback otherwise.
{% if subscriber.first_name != blank %}
{{ subscriber.first_name | capitalize }}
{% else %}
there
{% endif %}
Links
You can include properties within links as well, in order to send your contacts to a custom page.
Example:
<a href="https://www.yoursite.com/{{subscriber.PROPERTY_NAME}}">
Displaying a timestamp as a regular date
Let's say you have a contact property called expiration
(for a trial, maybe) that you store as a timestamp. If you wanted to display that expiration date in messages as a human-readable date, you can do so with liquid. There are a few different date filters you can use with this, but here we're just going to show you month name, day, and year.
Example
If you had a contact property called expiration
with a timestamp value of 1596153600
, you can do the following:
{{subscriber.expiration| date: "%B %-d, %Y"}}
The result in your message would be July 31, 2020.
The spaces, commas, etc between the date filters are included in the output. So if you want 31/07/2020 you'd do %m/%d/%Y
.
For the current date, you can use:
{{ 'now' | date: "%B %-d, %Y" }}
Displaying how many days left in a trial
{% assign current_date = 'now' | date: '%s' %}
{% assign future_date = subscriber.trial_end %}
{{ future_date | minus: current_date | divided_by: 86400 }}
Explanation
- You can get the current epoch time with
'now' | date: "%s"
. %s is a formatting option. - The
contact
.trial_end
date is in epoch time. - Since epoch time is in seconds, we're dividing by 86400 (number of seconds in a day) to get the number of days. Keep in mind that this is integer division so it'll be rounded down.
Show a different message based on day of week
{% assign day = 'now' | date: '%A' %}
{% if day == 'Friday' %}
Have a great weekend!
{% else %}
Cheers,
{% endif %}
Looping through properties
For this example, imagine each person has in their profile a list of friends, and you want to include this list in a message. Here's an example of what the data you send to Gist might look like in Javascript:
gist.identify({
email: "user@example.com",
friends: "Elaine, George, Kramer"
});
When you're composing messages for this contact, you can display his friend list using a Liquid for
loop:
{% assign friends = subscriber.friends | split: ", " %}
{% for person in friends %}
{{ person }}<br/>
{% endfor %}
And that's it! That'll display:
Elaine
George
Kramer
Conditional content
{% if subscriber.tags contains 'tag1' %}
This text will be sent to Contacts with the "tag1' tag on their profile.
{% endif %}
As seen inside Gist Email Composer: (Color added to show different components of Liquid Tag)
Add multiple variables to your liquid tag.
Gist allows you add more than one variable to your liquid tag. Now you can send 1 email, and Contacts will receive different messages depending on which property they have or don't have.
Example:
Email message example text is bolded.
{% if subscriber.tags contains "tag1" %}
This text will be sent to Contacts with the "tag1' tag on their profile.
{% elsif subscriber.tags contains "tag2" %}
This text will be sent to Contacts with the "tag2' tag on their profile.
{% else %}
This text will be sent to Contacts that do not have "tag1" or tag2" on their profile.
{% endif %}
As seen inside Gist Email Composer: (Color added to show different components of Liquid Tag)
These are the operators that can be used:
Comparison operators can be used with if,elsif, else and unless tags; they don’t work anywhere else in Liquid.
Note: The following would replace "contains" in the above examples.
{% if subscriber.property contains "tag1" %}
{% if subscriber.tags contains "tag1" %}
{% if subscriber.web_sessions <= "100" %}
`==` is equal to
`!=` is not equal to
`<` is less than
`<=` is less than or equal to
`>` is greater than
`>=` is greater than or equal to
`and`checks that both condition A and condition B exist
`or` checks that either condition A or condition B exist
`contains` checks for a substring within a string or an array
Using "Unless" Liquid Tags
There are certain situations where you won't want certain subscribers seeing certain messages. For these use cases, we've included a condition to keep certain properties from seeing a message.
Here is an example:
{% unless subscriber.tags contains 'zapier' %}
Welcome
{% endunless %}
So, essentially, you're replacing the word "if" for "unless" which will cause subscribers tagged with that property to not see the specific message within a liquid tag.
Filters
Filters can be used to change the output value or format of a Liquid tag. Below are some of the Liquid filters that are most commonly used in emails.
append
Joins two strings together and returns the value. For example:
Input | Output |
---|---|
{{ 15 | append: ‘%’ }} | 15% |
{{ subscriber.discount_amount | append: ‘%’ }} | 15% |
date
Converts a unix timestamp into another date format. The format for this syntax is the same as strftime.
Input | Output |
---|---|
{{ subscriber.collection_date }} | 1544268600 |
{{ subscriber.collection_date | date: “%e %B %Y” }} | 12 August 2018 |
{{ subscriber.collection_date | date: “%A %e %B” }} | Sunday 12 August |
{{ subscriber.collection_date | date: “%D” }} | 12/08/2018 |
{{ subscriber.collection_date | date: “%v” }} | 12-Aug-2018 |
Note: Unix time is UTC, see sections current date/ time and timezones to learn how to display the date and time for a different timezone.
divided_by
Divides a number by the number you specify. The value returned is rounded down to the nearest integer, if the divisor is an integer.
Input | Output |
---|---|
{{ 15 | divided_by: 3 }} | 5 |
downcase
Reformats the string as all lowercase letters.
Input | Output |
---|---|
{{ subscriber.viewed_product }} | Red Shoes |
{{ subscriber.viewed_product | downcase }} | red shoes |
first
Displays the first character or item in a string.
Input | Output |
---|---|
{{ subscriber.full_name }} | Sarah Jones |
{{ subscriber.full_name | first }} | S |
You can also include a split filter to display part of the string.
Input | Output |
---|---|
{{ “Alice, Sarah, Zach” | split: “, ” | first }} | Alice |
minus
Subtracts a number from another number.
Input | Output |
---|---|
{{ 10 | minus: 2 }} | 8 |
{{ 180.333 | minus: 8 }} | 172.333 |
You can also include the round filter to round the output to the nearest integer, or specifiy the number of decimal places you want to round to.
Input | Output |
---|---|
{{ 180.333 | minus: 8 | round: 2 }} | 172.33 |
{{ 180 | minus: 5.50 | round: 2 }} | 174.5 |
N.B. Trailing zeros are not displayed when using these standard Liquid maths filters. With Gist, you can use the custom Liquid filter, precision to display trailing zeros – for when you want to calculate and display prices/ currency formats in your emails.
modulo
Returns the remainder value after the division of one number by another.
Input | Output |
---|---|
{{ 5 | modulo: 2 }} | 1 |
{{ 180.57 | modulo: 4 }} | 0.57 |
plus
Adds a number to another number.
Input | Output |
---|---|
{{ 4 | plus: 6 }} | 10 |
{{ 163.539 | plus:8 }} | 171.539 |
prepend
Attaches a specified string to the beginning of a string.
Input | Output |
---|---|
{{ subscriber.total_paid }} | 42.95 |
{{ subscriber.total_paid | prepend: ‘$’ }} | $42.95 |
{{ subscriber.total_paid | prepend: ‘£’ }} | £42.95 |
replace
Replaces every occurrence of a specified substring with another, within a string.
Input | Output |
---|---|
{{ subscriber.subscription_plan }} | Gold subscription |
{{ subscriber.subscription_plan | replace: “subscription”, “plan” }} | Gold plan |
remove
Removes every occurrence of a specified substring within a string.
Input | Output |
---|---|
{{ subscriber.last_order_number }} | 00012336 |
{{ subscriber.last_order_number | remove: ‘000’ }} | 12336 |
times
Multiplies one number with another number and returns the value.
Input | Output |
---|---|
{{ 5.95 | times: 2 }} | 11.9 |
{{ 5.95 | times: 3 }} | 17.85 |
upcase
Changes the string to all uppercase letters
Input | Output |
---|---|
{{ subscriber.subscription_plan }} | Gold subscription |
{{ subsctiber.subscription_plan | split:” “ | first | upcase }} | GOLD |
Need Help?
If you have any further questions, please start a Live Chat. Just "Click" on the Chat Icon in the lower right corner to talk with our support team.