Personalization using Liquid

Blueshift offers various controls for personalizing your messages, as well as tools to make it easier to edit images and text blocks within the templates. We use open source version of Liquid templating language to reference and create personalized content.



Messages can be personalized using the following content:

1) User - Insert user specific attributes such as firstname, lastname, email and other custom attributes that you have sent through the Identify event or by uploading customer attributes through the dashboard
2) Catalog - Reference catalog variables (such as product name, image, url, etc.) in your triggered and recurring campaigns
3) Event Specific - Refer event specific variables in your messages

The Liquid template language provides logical operators to control how you want to output user and recommendation content in your template.

Liquid Basics

To learn more about Liquid and various filters, see Shopify's Liquid Basic Guide.

Certain Liquid filters that are custom to the Blueshift platform are listed below.



Some of these are described in detail below.

Any contains filter

This filter checks whether a reference string is present in a string or array.

{{ "ola" | any_contains:"a"}}
{% assign people = "fred, john, mary" | split: ", " %}
{{ people | any_contains: "m"}}


Image resize filter

This filter resizes an image.

{{ "" | resize_image: width:320,height:400}}


Hash algorithm filter

This filter converts a data string into a numeric string output of fixed length. For more information, see

sha1: {{ "lorem ipsum" | sha1 }}
sha256: {{ "lorem ipsum" | sha256 }}
md5: {{ "lorem ipsum" | md5 }} hmac_sha1: {{ "lorem ipsum" | hmac_sha1: "key1" }}
hmac_sha256: {{ "lorem ipsum" | hmac_sha256: "key1" }}
hmac_sha512: {{ "lorem ipsum" | hmac_sha512: "key1" }}
hmac_md5: {{ "lorem ipsum" | hmac_md5: "key1"}} base64_encoding: {{ "lorem ipsum" | b64_enc }}
base64_decoding: {{ "bG9yZW0gaXBzdW0=" | b64_dec }}


Shuffle filter

This filter shuffles the items in an array.

{% assign shuffled_products = products | shuffle %}

Time Zone filter

This filter formats ISO 8601 compliant dates into a given timezone. Here's a list of Time Zones this filter supports.

Here are some examples:

{% assign sign_up_date = "Thu Nov 29 2001 14:33:20 UTC" %}
{{ sign_up_date | time_zone: 'Hong Kong' }} => 2001-11-29 22:33:20 +0800
{% assign sign_up_date = "29/11/2001 00:00:00 -0900" %}
{{ sign_up_date | time_zone: 'Hong Kong' }} => 2001-11-29 17:00:00 +0800

Since this filter returns a date, the output can be chained with a date filter to format the value:

{% assign sign_up_date = "Thu Nov 29 2001 14:33:20 UTC" %}
{{ sign_up_date | time_zone: 'Hong Kong' | date: '%d/%m/%Y %H:%M:%S %Z' }} => 29/11/2001 22:33:20 HKT

You can also pass in an hour offset instead of a timezone:

{% assign sign_up_date = "2015-12-01 10:00" %}
{{ sign_up_date | time_zone: -7 | date: '%d-%m-%Y %H:%M' }} => 01-12-2015 03:00


Power Math filter

This filter returns the input to the exponent power

{{ 2 | pow: 3 }} // 8
{{ 2 | pow: -3 }} // 1/8
{{ -2 | pow: 3 }} // -8

AES 256 Encrypt/Decrypt filter

This filter returns a hex encoded AES 256 ciphertext of the input based on a given key, initialization vector and cipher name.

{{ '' | aes256_encrypt: '9cc25c7879fc94d5a19eeb8e47573b8423becb608a9a4e9d3c25c20aa7e04357','7bdc922b354cc8fa8d3f2910ba7cc411' }}

This outputs the following cypher text:


Cipher text can also be decrypted like so:

{{ 'e8420a7c166353e5a5c5b0aa21b4360b60e5ea357e8c0f36fac272c45cb20c6b' | aes256_decrypt: '9cc25c7879fc94d5a19eeb8e47573b8423becb608a9a4e9d3c25c20aa7e04357','7bdc922b354cc8fa8d3f2910ba7cc411' }} //

The default cipher used is aes-256-cbc, but aes-256-ecb is also available, by passing the cipher name as the 3rd option. Note the initialization vector is null for ecb mode.

{{ 'hamburger' | aes256_encrypt: '9cc25c7879fc94d5a19eeb8e47573b8423becb608a9a4e9d3c25c20aa7e04357', null, 'aes-256-ecb' }} //14d60bd236617adc84e23587f46addd1

Money filter

This filter formats numbers as currency. By default it uses the currency configured in your Account Profile

  • Sample Usage
{{ 19.99 | money }} // $ 19.99
{{ '19.99' | money }} // $ 19.99

The money filter accepts the following options:

Option Default Value Sample Values
use symbol true true, false
use space true  true, false
currency type The currency is configurable in the Account Profile "USD"


Here's a money filter that overrides the default account currency with Indian Rupees and eliminates the space between the currency symbol and number:

  • Sample Usage with currency and spacing options
 {{ 19.99 | money: true,false,'INR' }} // ₹19.99
  • Use the following variation of the money filter to output without decimals
{{ 1000000 | money_without_trailing_zeros : false }} // 1,000,000
{{ 1000000 | money_without_trailing_zeros }} // $ 1,000,000


Using liquid in template editor

You can use Liquid template language to personalize the content of the template including subject line. There are multiple options in the data of the template. Following sections describe how you can use Liquid template language in the email templates. 

1. User Attributes

Select a user in the HTML of the content tab (or in the text field of the visual editor) and simply start typing in the liquid variable syntax, {{user}}. You should see a list of variables (standard and extended/custom) available for the user. Ensure that you include a user in the Data tab. 



Variables can be categorized as standard or extended (non-standard). To reference extended variables, simply add extended_variables syntax in your liquid expression.

For example, an if statement could be used to greet a user by the user.firstname attribute, if it's available, but fallback to calling them "Friend" if the user.firstname attribute is not available.

  • FirstName Example
Hi {% if user.firstname == blank %}Friend{% else %}{{user.firstname | capitalize}}{% endif %}

2. Catalog Attributes

Blueshift makes it easy to reference catalog/content properties in your triggered and recurring campaigns. There are few steps to get started.

Reference products from Recommendation algorithm in the template. The catalog content can either be referenced via Products or a Recommendation Block array. See the following example of how you would reference products using both options in an email template.



Similar to user attributes, ensure that you pick a user and an algorithm in the Data tab prior to inserting product/recommendation variables. The recommendation output might have one or more blocks and depending upon the logic some of the blocks could be empty. By default the campaign execution will skip users if one of the blocks is empty, but depending upon how the template is coded, you may want to check or uncheck the flag. Simply start typing in the liquid variable syntax in the source editor and you should see a list of variables available for the user. For catalog content, you can type {{products}} or {{recommendation}}.



Sample liquid logic with for loop over recommended products.

{% for product in recommendations.block1.products %}


HTML code for rendering products

<a style="text-decoration: none;" href=''>

{% endfor %}

You can limit it to 5 in recommendation studio and use the loop above to iterate through them


3. Event Attributes

You can also personalize your templates by inserting event variables directly in the template. There are a few personalization options:

  1. User attributes: See above to insert user variables. For example, {{user.firstname}}, {{user.extended_attributes_city}}
  2. Product Data: In order to do this, the event must contain product_id or product_ids. The variable to use is {{}}
  3. Event Properties: Simply use the {{attribute_name}} syntax to reference your event variables. For example, for the sample event below you would use {{email}}, {{sku}}, {{bsft_event_context.first_name}}, etc. in your template.


  "_browser_platform": "Linux",
  "_browser_type": "Chrome",
  "_browser_version": "37.0.2062.117",
  "cookie": "06a99b5f-er4da-8cec-e98d-c0b707757c11",
  "customer_id": "558490",
  "email": "",
  "event": "purchase",
  "ip": "",
  "referrer": "",
  "revenue": "0",
  "session_uuid": "4bdbd6874-9f36-404b-a174-8a545d7fa4e0",
  "sku": "t-shirt",
  "url": "",
  "user_agent": "Ruby",
  "order_id": "mjo654961905",
  "timestamp": "2017-02-09T14:55:41Z",
  "site": "",
  "product_ids": [
  "event_uuid": "53ed44ee-eef9-11e6-890c-0242ac110008",
  "timestamp_epoch": 1486652141,
  "account_uuid": "03b11234d7-7d3a-434a-96a0-cb790c8dd91e"

To preview these personalization variables in the template, you will need to paste a sample event JSON payload in the Preview Data section of the Data tab or choose an event from the list.



4. Global Variables

Preview Email: You can use the variable {{email_preview_link}} to create an online version of your email template.  

<a href="{{email_preview_link}}">Click here to preview</a>


Unsubscribe: Use the variable {{unsubscribe_link}} in your HTML templates. When the email is sent out, the variable link expands to a hyperlink that includes a hash of the user's ID. When the user clicks on it, we track the click and unsubscribe the user.


Resubscribe: You may want to send a confirmation email when a user unsubscribes from your mailing list. However, you could also include an option to resubscribe by inserting the variable {{resubscribe_link}} in your HTML templates.


Open Tracking Pixel

An open tracking pixel is added to the end of each email body by default. However, accounts can opt-in to position this pixel manually. If manual positioning is enabled, the pixel is inserted into the email markup by adding the following snippet. 

<img src="{{bsft_open_pixel}}"/>
If this snippet is missing from your template, then the open tracking pixel will be added to the end of the email body automatically.
Skipping Link Tracking
We have a specific attribute for this purpose.   A "bsft-no-track" attribute that you can add to relevant links. It will remove all blueshift tracking from the specified link and you use it like this:
<a href=" b sft -no-track>email link</a>

External fetch

You can fetch dynamic content from an external source that you specify in the Data tab. You can use Liquid variables to use the content that you fetch from an external source in your email templates. For more information on using external fetch in template editor, see this doc.


Using liquid in email triggers

In addition, you can specify a liquid variable in the From Name, From Address, and Reply To Address fields in a campaign's email trigger.  You can use the liquid variables with appropriate attributes to dynamically populate these fields of the email. For example, if you want the email to have your customer success manager's email address in the From Address field, you can specify the appropriate liquid variable in the trigger. Our platform uses the value of the variable in the From Address field of the email.



Issues with HTML tags in liquid templates

Ensure that the content of your Liquid template does not include HTML tags enclosed in angular brackets, such as <a>, <p>, <ul>, and the rest. If you use an HTML tag in your liquid template, our template rendering engine fails to differentiate between the HTML tag and a string variable. This breaks the template and produces buggy messages. 

Was this article helpful?
1 out of 1 found this helpful



Please sign in to leave a comment.