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 Design 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.

Determine the Liquid syntax for merge tags

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

Any merge tag’s Liquid syntax can be obtained through any email message’s Design page.

  1. On the Design page of an existing 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 or activity attribute from the list:

    • For a field item:

      1. Select the specific field.

      2. Complete your chosen field’s remaining value options.

      3. Click Add to insert the field value at your chosen location.

    • For an activity’s attribute:

      1. Select the activity’s specific attribute.

      2. Complete your chosen activity’s remaining attribute value options.

      3. Click Add to insert the activity’s attribute value at your chosen location.

    Once added the field or activity’s attribute is displayed in its Liquid syntax form, which can be used with other Liquid syntax described on this page to control content dynamically and with logical statements.

Filters

Liquid syntax supports its own filters feature, where each filter is used to modify a merge tag’s number, string, or object value.

Learn more about Liquid syntax filters in the Filters section of the Liquid template language site, which begins with the abs filter.

Be aware that some filters can be strung together to further modify your merge tag’s value. In such cases, each filter is separated by a pipe (|) character.

While all relevant Liquid syntax for merge tags can be determined using the procedure above, this section lists filters that are:

  • not readily accessible through the Insert merge tag feature, or

  • commonly used but have exceptions.

default

When adding a merge tag, many allow you to specify a default value, which is the fallback value used when the merge tag itself returns no value.

Built-in person field example
{{ people.total-spent | decimal: 'two', '$' | default: '0' }}

represents a person’s Total spent dollar amount to two decimal places, which displays $0.00 if this merge key has no value yet.

Non-conventional default filters

When determining the Liquid syntax for some merge tags, the default filter may be different and/or might be combined with the functionality of other filters.

Built-in phone number field example
{{ people.phone-number | hideCountryCodeAndDefault: false, '' }}

In this case, the default is combined with the functionality of another custom filter. With this example, this merge tag ensures that the phone number’s country is displayed, and no default value is specified.

numberWithDelimiter

When adding a merge tag that displays a whole or decimal number, you can add the numberWithDelimiter fliter to break up large numbers by 3 digit delimiters with the following syntax:

{{ people.custom.int | numberWithDelimiter: 'en', 'whole'}}

The numberWithDelimiter filter takes two values:

  • The first value specifies the two-letter country identifier that defines the type of delimiter used - e.g. a comma (,) or a period (.). Four-letter locale identifiers are also supported - e.g. en-US, en-GB, etc.
    Learn more about what country and locale identifiers are supported in the JavaScript: Language Tags (BCP 47) post.

  • The second value specifies if the number is a whole (integer) or one- or two-decimal (real) number. For decimal numbers, specify the value one or two accordingly.

In the example above, if people.custom.int's value was 1000000, then this numberWithDelimiter filter would display this value as 1,000,000.

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 control flow tags) 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.

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 whose value is 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 %}

Variable tags

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

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

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:

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 Design page, determine the Liquid syntax for the activity’s attribute (merge tag) that contains the image URL.

  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 (e.g. activity.custom.booking-complete.destination-image).

    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.