Personalizing campaign content with Liquid

Ortto supports the use of Liquid template language syntax (Liquid syntax) in email and SMS messages of campaigns.

While a merge tag allows you to customize email and SMS message content based on a person, organization or custom field, or an activity’s attribute value, using merge tags in combination with the Liquid template language provides a powerful and flexible way to personalize your email and SMS messages further with dynamic content and logic.

This means that in addition to including your customer data platform (CDP) and activity attributes in your emails, you can use logic such as "if" statements (control flows with operators), along the many Liquid filters that can be used to modify merge tag values.

Liquid syntax can be used within the Content pages of email and SMS message campaigns, including emails and SMS messages used within playbook and journey campaigns.

Ortto only supports Liquid syntax usage in lower case. Therefore, all merge tags must be in specified in lower case.

About merge tags and Liquid syntax

If you are new to working with merge tags and Liquid syntax, here are is an introduction to the syntax.

Double curly braces (objects)

Items contained in double curly braces will produce an output of the specified object and value. For example {{ people.first-name }} will output the first name (value) of the person (object) receiving the message. So Congratulations {{ people.first-name }}! will display the recipient’s first name when they read the email (e.g. "Congratulations John!").

Single curly braces (delimiters)

Single curly braces with percentage symbols (delimiters) are used for containing the logic that determines what content is visible, and won’t produce an output. For example, {% if activity.shopify.ordered-product.quantity == 1 %} will show content placed after the braces only to people who have ordered once from your Shopify store.

Items in curly brace percentage delimiters that contain statements such as "if" need to have a terminating statement to be valid. That is, a statement beginning {% if …​} will need to have a terminating statement such as {% endif %} located where you want the if condition to end.

If you start writing a condition that is contained in curly brace percentage delimiters and you add a merge tag to the statement, the merge tag will be inserted contained in double curly braces. You’ll need to delete this set of double curly braces and leave the merge tag object and value. For example adding a merge tag to

{% if %}

will result in

{% if {{ people.city }} %}

which won’t be valid. So remove the double curly braces to complete the statement

{% if people.city == 'London' %}

Operators

Operators are used to determine your statement logic. Ortto supports the following operators:

Operator Description

==

equals

!=

does not equal

>

greater than

<

less than

>=

greater than or equal to

⇐

less than or equal to

or

assesses whether the boolean (true/false) value of one or more merge tags is true

and

assesses whether the boolean (true/false) values of all merge tags are true

contains

checks for the presence of a string or substring (part of a string), usually a merge tag’s value

You can use operators to determine the values by which you wish to control your message content. Using an earlier example, the statement {% if people.city == 'London' %} will determine that only people whose city value is London will see the subsequent content.

Or, you could show a coupon only to people who are subscribed to your mailing list and have made at least 1 purchase in your Shopify store with {% if people.email-permission == 'yes' and activity.shopify.ordered-product.quantity >= 1 %}

Determine the Liquid syntax in email and SMS messages

When using Liquid syntax to provide dynamic content and logic with merge tags in your emails and SMS messages, you need to determine and use the Liquid syntax for merge tags, which is the raw syntax for these merge tags.

If a particular value for a merge tag cannot be found by Liquid or you have perhaps mistyped the tag object and value, Liquid will output nothing.

We strongly encourage you populate the default field option when inserting the merge tag (or manually type in the | default: filter) whenever possible in places where you are not certain that the merge tag will have the value. Learn more about default under Liquid filters.

Use Liquid in email messages

You can view and edit the Liquid syntax for merge tags when creating an email message, in the email Content page.

  1. On the Design page of an email message, click within an existing TEXT box.

    If an existing TEXT box is not available in the email content editor section of the Design page, drag a new TEXT box across to the email content editor, and click within this new TEXT box.

  2. In the TEXT box toolbar, click Insert merge tag.

  3. In the Insert merge tag dialog, select the relevant field item (Person, Organization, or a data source) or activity attribute from the list:

    1. Select the field category or an activity name.

    2. Select the field or activity attribute.

    3. Determine a default value as required.

    4. Click Add to insert the field or activity attribute value at your chosen location.

insert merge tag
A merge tag inserted on its own

Once added, the field or activity attribute is displayed as an object in its Liquid syntax form, at which point you can add a value and other Liquid syntax described on this page (such as control flow, iteration and variable tags, and filters) to control content dynamically and with logical statements.

merge tag w syntax
The merge tag with Liquid syntax
Using the Send test email feature will run the Liquid code for you so you can identify any areas that are not displaying as you intended, before you send the message to your audience.

Use merge tags in URLs

You can create a dynamic URL by inserting a merge tag as the URL. For example, where you have a custom person field that contains a registration or login URL, you can use that field as a merge tag in your URL configuration.

To do so:

  1. On the Design page of an email message, click within an existing TEXT box.

  2. Type your text and highlight the word you wish to add a link to, e.g. register.

  3. Click the link icon and in the Insert link box, at URL insert the merge tag for your custom person field, e.g. {{people.custom.register-url}}.

  4. Edit any other link settings as required then click OK to finish.

dynamic url
URL with merge tag

Another way to use merge tags as links could be to take a potential customer back to their abandoned cart using merge tags for the products left in the cart (where you have an e-commerce data source connected to your Ortto account).

For example, you could add a button with the text Complete your order and for the URL, insert a merge tag such as Shopify’s {{activity.shopify.abandoned-checkout.abandoned-checkout-url}}.

Use Liquid in SMS messages

You can use Liquid syntax for merge tags when creating an SMS message, in the SMS Design (A/B) page.

  1. On the Design (A/B) page of an SMS message, click within the Text section.

  2. Type in the Liquid syntax and any merge tags you wish to use in raw syntax format (instead of using the insert merge tag feature people).

The SMS preview will show the raw format of your Liquid syntax, however the content will be displayed with the relevant values populated (such as a person’s first name if person.first-name is used) when the recipient views the SMS message.

sms liquid
SMS message with complex Liquid syntax

The above approach is for if you wish to insert complex Liquid syntax. For simple cases, you can of course still insert merge tags, using the people person icon, within your message content, such as where you want to personalize the message with the recipient’s first name.

simple sms merge tag
SMS message with merge tag

Translate campaign content with Liquid

Email message language translation is performed by adding Liquid syntax in the Design step when creating an email.

Ortto does not translate message content for you; you need to write any text content in the relevant language. For example, an email campaign that supports both English and Spanish languages will need to have subject lines and message text written in both English and Spanish. The relevant message text must be surrounded by conditions which determine that English readers see the English text, and Spanish readers see the Spanish text.

There are a number of ways you can set language conditions.

In the text boxes, create conditions to determine what content users see, depending on their preferred language. You can combine all language conditions and text content within a text box, such as if you want to write greetings in different languages.

english spanish syntax

You can frame content with Liquid syntax in text boxes to show different content depending on the language. In the below example, the campaign is setup to translate to Spanish, so using the syntax displayed, English readers will see the top image, but Spanish readers will see the bottom image.

syntax framing

You can also set conditions for an entire row. To do so, click on the row, then in the Rows settings on the right, click Add condition. Enter your name, description, and before and after conditions, then Confirm. The row is now set to display to recipients with the preferred language you specified.

lang row condition
lang row condition 2

Other handy operators are or and contains, such as:

  • {% if people.language == 'en-us' or people.language == 'en-gb' %} Display content for all English (US and UK) readers {% elsif people.language == 'es' %} Display content for Spanish readers {% endif %}

  • {% if people.language contains 'en' %} Display content for all English (US and UK) readers {% elsif people.language == 'es' %} Display content for Spanish readers {% endif %}

The values for the languages Ortto currently supports for translation are:

  • Chinese (simplified) — zh-cn

  • Chinese (traditional) — zh-tw

  • Dutch — nl

  • English (UK) — en-gb

  • English (US) — en-us

  • Finnish — fi

  • French — fr

  • German — de

  • Italian — it

  • Polish — pl

  • Russian — ru

  • Spanish — es

Learn more about translating email message content in Creating an email campaign.

Control flow tags

Liquid syntax supports control flow tags, which in combination with operators determine the conditions under which blocks of Liquid code (contained within the curly brace percentage delimiters) are executed.

As indicated in the Liquid documentation, Ortto supports the following sets of control flow tags:

  • if, elsif*, else*, and endif

  • unless, elsif*, else*, and endunless

  • case, when, else*, and endcase

* optional tags

Each end…​ tag ends a control flow block (such as endif).

Example simple if block
{% if people.custom.special-offer %}
Bonus: for being a loyal customer, we'd like to offer you half off your next purchase. Use the coupon code LOVE to redeem this offer.
{% endif %}

where people.custom.special-offer is a custom boolean-type field with a value of true or false, and its value is evaluated as a Liquid syntax truthy.

Example if block with optional elsif and else tags
{% if organization.employees > 50 %}
With a large organization like yours, communication is key.
{% elsif organization.employees > 5 %}
In small-to-medium businesses like yours, the key is balance.
{% else %}
In a micro-organization like yours, you need to save every dollar.
{% endif %}

In the below example, you are asking your audience to visit your Twitter profile and you have two fields that mark the person as having done so: people.custom.twitter-ready or people.custom.clicks contains.

Example unless block with else tags
{% unless people.custom.twitter-ready == true and people.custom.clicks contains ' https://mytwitter.url ' %}
Thanks for checking us out on Twitter!
{% else %}
Go check us out on Twitter!
{% endunless %}

Iteration tags

You can use iteration tags such as for, cycle and tablewrow to output data that is an array type (a collection of values).

For example, to show a person’s tags, you can use:

{% for tagID in people.tag %} {{ tagID }} {% endfor %}

If you have a custom field named "Favorite brands" that is a multi-select type, with the values [nike, adidas, puma], you can output one of the values with:

{% for b in people.favourite-brands %} {{ b }} {% endfor %}

and the output will be adidas.

You can also iterate on activities, such as if you want to send an email to a person who left items in their shopping cart without checking out:

Are you still interested in these items? {% for item in activity.shopify.abandoned-cart.line-items %} {{ item.name }} {% endfor %}

which will output the name of the item/s which the customer had in their abandoned cart.

Learn about using for to loop through a JSON object at Access JSON objects with Liquid.

Variable tags

Liquid syntax also supports the ability to assign values to variables.

Using variables may be useful when creating your own email and SMS templates, when you might require more sophisticated handling of merge tag values.

Liquid variables available to use are:

  • assign

  • capture

  • increment

  • decrement.

When declaring a variable in Ortto using a Liquid variable tag, you must begin the variable name with var so that Ortto can recognize it as a declared variable.

For example, this declared variable named cities begins with var, and you want to join the values of varcities with and in your output:

{% assign varcities = "London, New York" | split: ", " %}
{{ varcities | join: " and " }}

to output London and New York.

One way you could use a variable tag is to assign a variable with the value of now to determine the time (using the strftime syntax) you send the message (rather than when the recipient sees the message)

{% assign vartodaydate = 'now' | date: '%s' %}
{% assign varexpiry = people.custom.expire-date | date: '%s' %}
{% if varexpiry < vartodaydate %}
Your subscription expired today
{% endif %}

Filters

Ortto supports the use of all Liquid filters, where a filter is used to modify a merge tag’s number, string, or object value. Learn more about filters, including exceptions for using Liquid syntax in Liquid filters.

Other Liquid syntax and tags

In addition to the tags mentioned above, Liquid syntax also supports the following additional features and tags, which may be useful in your email and SMS campaign messages.

Truthy and falsy

Truthy and falsy control flow tests on both boolean and non-boolean (true/false) data types, such as the simple if block example above.

As another example, if you have a boolean custom field called Is VIP, then you can use {% if people.custom.is-vip %} VIP special content {% endif %} to only show the content to your VIPs.

Or you could show content to people who have not yet verified their email in Shopify: {% unless people.shopify.verified-email %} Please verify your Shopify email {% endunless %}

Whitespace control syntax

Whitespace control syntax is used to omit blank lines resulting from the processing of other Liquid syntax tags. This is achieved by adding a hyphen to one or both of your delimiters or double curly braces, e.g. {%-, {%- …​ -%}, or -}}

This can be useful to ensure your text content is formatted correctly, where

Hey, {{ people.first-name | default: 'there' }}  ! Thanks for subscribing!

will result in

Hey, Patricia ! Thanks for subscribing!

adding the whitespace control syntax will remove unwanted spaces

Hey, {{ people.first-name | default: 'there' -}}  ! Thanks for subscribing!

to output

Hey, Patricia! Thanks for subscribing!

Display an image from an activity’s attribute

It is possible to display an image in a campaign’s email message, where this image is sourced from an activity’s attribute, whose value is a image URL.

For example, a custom activity called Booked trip consists of the following information and attributes:

  • Booked trip (name of activity)

  • Trip name

  • Destination

  • Destination image (containing a valid image URL)

  • Arrival date

  • Departure date

After a customer complete’s their booking, you may want to send the customer a confirmation email message that displays all details of this activity’s attributes for the booked trip, including the destination image (above).

To display an image from an activity’s attribute in an email message for a playbook, journey or email campaign:

  1. From your email message’s Content page, determine the Liquid syntax for the activity’s attribute (merge tag) that contains the image URL (e.g. activity.custom.booking-complete.destination-image).

  2. Drag a new HTML box across to the email content editor, and click within this new HTML box (containing the text I’m a new HTML block) to reveal its CONTENT PROPERTIES on the right.

  3. Remove the existing HTML code and replace it with:

    <img src="{{ LIQUID-SYNTAX-FOR-YOUR-ACTIVITYS-ATTRIBUTE-WITH-IMAGE-URL }}">

  4. Replace LIQUID-SYNTAX-FOR-YOUR-ACTIVITYS-ATTRIBUTE-WITH-IMAGE-URL with Liquid syntax you generated in step 1 above.

    If the availability of a valid image URL for this activity’s attribute cannot be guaranteed, you can use Liquid syntax’s [default] filter to specify a fallback image, e.g.

    {{ activity.custom.booking-complete.destination-image | default: 'my.cdn.url/image.png' }}

    The image may appear broken in the editor. However, if the image URL of the activity attribute is valid, the image will be displayed correctly when the email is sent. It is recommended that you send a few test email messages first before actually sending your email campaign and/or making this email live.