Ortto allows you to use Liquid template language in your email, SMS, and push notifications. This helps you personalize content by combining merge tags with Liquid syntax for dynamic messages.
What is a Merge tag?
Merge tags let you customize content based on individual, organization, custom fields, or activity attributes.
Why use Liquid syntax?
By using Liquid, you can enhance your messages with logic (like "if" statements) and various filters to adjust merge tag values. This means you can include specific customer data and create more engaging and relevant content.
Where can you use Liquid syntax?
You can use Liquid syntax in the content sections of your email and SMS campaigns, including those within playbook and journey campaigns.
NOTE: Please remember that Ortto only supports Liquid syntax in lower case. This means all merge tags must be written in lower case to function correctly.
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 email and SMS messages, and push notifications, you need to determine and use the Liquid syntax for merge tags, which is the raw syntax for these merge tags.
NOTE: 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.
On the Content page of an email message, click within an existing Text box.
In the Text box toolbar, click Insert merge tag.
In the Insert merge tag dialog, select the relevant field item (Person, Organization, or a data source) or activity attribute from the list:
Select the field category or an activity name.
Select the field or activity attribute.
Determine a default value as required.
Click Add to insert the field or activity attribute value at your chosen location.
A merge tag inserted on its own
NOTE: If an existing Text box is not available in the email content editor section of the Content page, drag a new Text box across to the email content editor, and click within this new Text box.
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.
The merge tag with Liquid syntax
TIP: 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:
On the Content page of an email message, click within an existing Text box.
Type your text and highlight the word you wish to add a link to, e.g. register.
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}}.
Edit any other link settings as required then click OK to finish.
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 ecommerce data source connected to your Ortto account).
EX:
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}}.
Merge tags can be used to fill in the entire URL or be inserted as dynamic pieces to an existing URL, s adding custom parameters in UTMs.
This allows you to:
Direct contacts to targeted URLs based on their details, or
Pass contact information to other systems via the URL, like pre-filling fields in Typeform.
EX:
If your Typeform form is set to prefill fields, you can use the merge tag for the fields to provide those items to the form in its URL.
Here's an example of how you can input the merge tags for name and email:
If you are sending an email campaign using your own HTML template, you can use the following Liquid syntax for the special links for the unsubscribe, preferences, view online, and forward actions. (These special links are usually available at the Content step when creating an email campaign, in the text box options.)
Unsubscribe: {{ urls.unsubscribe }}
Update your preferences: {{ urls.preferences }}
View online: {{ urls.viewonline }}
Forward: {{ urls.forward }}
Use Liquid in SMS messages
You can use Liquid syntax for merge tags when creating an SMS message, in the SMS Content page.
On the Content page of an SMS message, click within the Text section.
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 ).
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 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 person icon, within your message content, such as where you want to personalize the message with the recipient’s first name.
SMS message with merge tag
Use Liquid in push notifications
You can use Liquid syntax for merge tags when creating push notification, in the push Content page.
On the Content page of push notification, click within the Text section.
In the Title or Message sections, 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 ).
The push notification preview will show the raw format of your Liquid syntax, however the content will be displayed with the relevant values populated when the recipient views the push notification.
Push notification 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 person icon, within your notification content, such as where you want to personalize the notification with the recipient’s first name.
Push notification 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.
NOTE: 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. Learn more about this, including supported languages and recipient language preferences, on the How to display translated email message content page under Managing campaigns.
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 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
{% unless people.custom.twitter-ready == true and people.custom.clicks contains 'https://mytwitter.url' %}
Go check us out on Twitter!
{% endunless %}
Iteration tags
You can use iteration tags such as for, cycle and tablerow to output data that is an array type (a collection of values).
For example, 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.favorite-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.
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.
NOTE: 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)
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.
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
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:
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.
Remove the existing HTML code and replace it with: <img src="{{ LIQUID-SYNTAX-FOR-YOUR-ACTIVITYS-ATTRIBUTE-WITH-IMAGE-URL }}">
Replace LIQUID-SYNTAX-FOR-YOUR-ACTIVITYS-ATTRIBUTE-WITH-IMAGE-URL with Liquid syntax you generated in step 1 above.
TIP: 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.
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.
Tag support in liquid
Tags added to your contacts can be utilized in your Liquid syntax.
While this functionality isn't directly displayed in the Insert merge tag dialog, you can reference tags using two methods:
Direct tag match:
Exclusively returns results for contacts with a single tag applied.
Tag contains:
Returns results based on partial tag matches.
This method ensures that liquid is returned for any record with the specified tag, unaffected by other tags.
NOTE: This activity does not utilize tag-added data, and therefore, it is not affected by any data retention settings.
Audience support in liquid
You can use the audiences that your contacts belong to in your Liquid syntax .
Although this functionality isn't shown directly in the Insert merge tag dialog, you can reference audiences using the audience's ID. This ID can be found in the URL for the audience.
Example of where an audience's ID is located in its URL.
EX:
{% if people.member-of-audience-PlaceholderAudienceID %}
