> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/crm-automation/communication-channels/liquid-email.md).

# Liquid Email

Liquid is an open-source template language designed to help you build dynamic, data-driven content, making it perfect for personalized and interactive emails. With Liquid, you can embed variables and conditionals directly into your HTML. This allows you to create highly customized emails that cater to individual recipients, leading to more engaging and effective campaigns.

How Does It Work?

* **Variables**: Placeholders in the HTML that get replaced with actual data when the email is generated.
* **Conditionals**: Control the content display based on specific criteria, making the email content adaptable to different scenarios.

{% hint style="info" %}
**Note**: You can utilize Smartico dynamic tags including <mark style="color:orange;">`state`</mark>, <mark style="color:orange;">`campaign`</mark>, <mark style="color:orange;">`event`</mark>, and <mark style="color:orange;">`label`</mark> tags. Note that <mark style="color:orange;">`state`</mark>, <mark style="color:orange;">`campaign`</mark>, and <mark style="color:orange;">`event`</mark> tags are processed directly inside Liquid logic and conditions, while <mark style="color:orange;">`label`</mark> tags are resolved after Liquid rendering and cannot be used as variables inside Liquid conditionals (such as {% if %} statements).
{% endhint %}

To better understand the capabilities of Liquid lets follow a couple of examples.

## **Use of fallback**

When greeting users, it's important to display their names. However, if some users haven't set up their names, you can use their username (or specific prefix like Mr, player, friend, etc.) as a fallback.

```liquid
Hello, {{ state.user_first_name | default: state.core_username }}!
```

<mark style="color:blue;">**Set up name Result:**</mark> <mark style="color:blue;">Hello, Christopher!</mark>\ <mark style="color:blue;">**Not setup Result:**</mark> <mark style="color:blue;">Hello, christopher90!</mark>

## **Use of conditions & variables**

Using conditions and variables in Liquid allows you to display personalized user information, significantly boosting user retention and giving the user a sense of exclusivity and personal attention.

For example, below, we are dynamically displaying the day of the week the email is sent, showing information of the last deposit, current balance amount, and showing countdown for promotion. At the same time, all that info is personalized for each recipient.

In this example, `days_since_deposit` is a variable you set yourself with `{% assign %}` before this text. It is not a Smartico tag, and if it is not set, the number is empty.

{% code overflow="wrap" %}

```liquid
Happy {{ 'now' | date: "%A" }}! We miss you! You haven't made a deposit for 
{% if days_since_deposit < 7 %}
  {{ days_since_deposit }} days
{% elsif days_since_deposit < 30 %}
  more than a week
{% else %}
  more than a month
{% endif %}
and your balance is 
{% if state.acc_real_balance < 10 %}
  really low at {{ state.acc_real_balance | plus: 0 }}$
{% else %}
  at {{ state.acc_real_balance | plus: 0 }}$
{% endif %}.
We have an exciting offer for you! If you deposit in the next {{ 'now' | date: "%H" | minus: 23 | abs }} hours and {{ 'now' | date: "%M" | minus: 59 | abs }} minutes, we will accumulate an additional 50% bonus to your deposited amount.
```

{% endcode %}

<mark style="color:blue;">**Example Result:**</mark>\ <mark style="color:blue;">Happy Friday! We miss you! You haven't made a deposit for 5 days, and your balance is really low at 3$.</mark>\
\ <mark style="color:blue;">We have an exciting offer for you! If you deposit in the next 20 hours and 50 minutes , we will accumulate an additional 50% bonus to your deposited amount.</mark>

<mark style="color:blue;">**Example Result 2:**</mark>\ <mark style="color:blue;">Happy Saturday! We miss you! You haven't made a deposit for more than a month and your balance is at 20$.</mark>\
\ <mark style="color:blue;">We have an exciting offer for you! If you deposit in the next 23 hours and 4 minutes , we will accumulate an additional 50% bonus to your deposited amount.</mark>

## **Set a specific timezone**

Simply adjust the time to a specific timezone used by the email recipient so they don’t get confused by the system time, which is in UTC time.\
\
Here is a more detailed explanation:\ <mark style="color:purple;">`"now" | date: "%s"`</mark> - gives us the current time of the Smartico system in UTC timezone.

<mark style="color:purple;">`current_time | plus: 7200`</mark> - is where we set the offset by seconds; plus/minus are used to determine if you want to offset ahead/behind, 7200 seconds = 2 hours

<mark style="color:purple;">`{% assign %}`</mark> is used to create and store a value in a variable which you can manipulate or in this instance, use for calculation

<mark style="color:purple;">`{{ adjusted_time | date: "%Y-%m-%d %H:%M" }}`</mark> - is what we print to the user, and we define the format <mark style="color:purple;">`%Y-%m-%d %H:%M`</mark> (year, month, date, hour, minute)

<mark style="background-color:yellow;">Warning: beware that the values are case sensitive, for instance %M shows minutes and %m shows month</mark>

{% code overflow="wrap" %}

```liquid
{% assign current_time = "now" | date: "%s" %}
{% assign adjusted_time = current_time | plus: 7200 %}
{{ adjusted_time | date: "%Y-%m-%d %H:%M" }}
```

{% endcode %}

<mark style="color:blue;">**Result:**</mark>

<mark style="color:blue;">2025-10-27 11:00</mark> \*(when your current time is 2025-10-27 09:00)

### Send-Time Evaluation and Countdown Limitations

All Liquid tags, variables, and date calculations (such as `"now"`) are evaluated and frozen at **send time** when the email activity is generated, not when the recipient opens the message.

If you calculate a countdown using `"now"`, the resulting hours and minutes reflect the remaining time at the moment the email was dispatched. For real-time animated countdown timers that update dynamically upon email opening, embed an external countdown timer image URL.

## **Format Date/Time**

You can format a date in Liquid using the `date` filter.

The general syntax is

`{{ date_variable | date: "format_string" }}`

Here are some common format specifiers:

| **Specifier** | **Description**                       | **Example Output (for Jan 02, 2025 at 3:04 PM)** |
| ------------- | ------------------------------------- | ------------------------------------------------ |
| `%a`          | Abbreviated weekday name              | Thu                                              |
| `%A`          | Full weekday name                     | Thursday                                         |
| `%b`          | Abbreviated month name                | Jan                                              |
| `%B`          | Full month name                       | January                                          |
| `%d`          | Day of the month, zero-padded (01-31) | 02                                               |
| `%e`          | Day of the month, space-padded (1-31) | 2                                                |
| `%m`          | Month as a decimal number (01-12)     | 01                                               |
| `%y`          | Year, last two digits (00-99)         | 25                                               |
| `%Y`          | Year with century                     | 2025                                             |
| `%H`          | Hour in 24h format (00-23)            | 15                                               |
| `%I`          | Hour in 12h format (01-12)            | 03                                               |
| `%M`          | Minute (00-59)                        | 04                                               |
| `%S`          | Second (00-59)                        | 39                                               |
| `%p`          | AM or PM (uppercase)                  | PM                                               |
| `%P`          | am or pm (lowercase)                  | pm                                               |
| `%c`          | Date and time representation          | Thu Jan 02 15:04:39 2025                         |
| `%D`          | Short MM/DD/YY date                   | 01/02/25                                         |

Example

```
Last updated: {{ "now" | date: "%Y-%m-%d %H:%M:%S" }}
```

### Syntax Validation and Template Errors

Liquid resources require strictly valid syntax. If a template contains an unclosed block tag or an unregistered tag, the template engine will fail to compile the message. This causes a delivery failure for affected recipients.

To prevent delivery issues, use the Back-Office email editor to check for syntax error indicators and preview the rendered output with a test user before launching campaigns.

## **Set a specific translation**

If we want to use dynamic tags like day/month but the recipients are from different countries and speak different languages we can assign specific translations. Smartico's Liquid engine does not support map (hash) values such as `{ "FR": ... }` inside `assign`, so keep each translation in a comma-separated list and pick the item by the day number (`%w`: 0 = Sunday … 6 = Saturday):

{% code overflow="wrap" %}

```liquid
{% assign day_index = "now" | date: "%w" | plus: 0 %}
{% if state.core_user_language == "FR" %}
  {% assign days = "Dimanche,Lundi,Mardi,Mercredi,Jeudi,Vendredi,Samedi" | split: "," %}
  {% assign translated_day = days[day_index] %}
{% elsif state.core_user_language == "ES" %}
  {% assign days = "Domingo,Lunes,Martes,Miércoles,Jueves,Viernes,Sábado" | split: "," %}
  {% assign translated_day = days[day_index] %}
{% else %}
  {% assign translated_day = "now" | date: "%A" %}
{% endif %}
{{ translated_day }}!
```

{% endcode %}

<mark style="color:blue;">**Spanish user result for Friday:**</mark> <mark style="color:blue;">Viernes</mark>\ <mark style="color:blue;">**French user result for Friday:**</mark> <mark style="color:blue;">Vendredi</mark>

## **Reminders for missions, jackpots etc.**

Boost user engagement by sending email reminders to users when they have progressed in missions but haven’t finished them yet to remind them and trigger user activation. Give users a nudge on the rising Jackpot and motivate them to play more.

**Jackpot amount:**

{% code overflow="wrap" %}

```liquid
{{ state.user_first_name }}, our Amazing Jackpot has reached an astonishing {{state.jackpot_amount}}. Hurry up and play for a chance to win it!
```

{% endcode %}

<mark style="color:blue;">**Result:**</mark> <mark style="color:blue;">Christopher, our Amazing Jackpot has reached an astonishing 67000$. Hurry up and play for a chance to win it!</mark>

**Missions in progress:**

{% code overflow="wrap" %}

```liquid
{{ state.user_first_name }}, do you know that your <img src="{{event.meta.image_url}}" width="32" height="32" alt="{{event.meta.name}}"/> “{{event.meta.name}}” mission is still in progress? Finish it and you will get {{event.meta.reward}}!
```

{% endcode %}

<mark style="color:blue;">**Result:**</mark> <mark style="color:blue;">Christopher, do you know that your “Play 5 Mini-Games” mission is still in progress? Finish it and you will get 10 Free Spins!</mark>

## **URL Encoding and Decoding**

URLs can be encoded and decoded directly within your email template using \`url\_encode\` and \`url\_decode\`.

{% code overflow="wrap" %}

```liquid
{{ "example.com/questions/what-is-the-question?#Answer#1" | url_encode }}
```

{% endcode %}

<mark style="color:blue;">**Result:**</mark> <mark style="color:blue;">example.com%2Fquestions%2Fwhat-is-the-question%3F%23Answer%231</mark>

\
Many more...
------------

Check all Liquid supported filters and commands below:

{% embed url="<https://shopify.github.io/liquid/>" fullWidth="false" %}

### Dynamic Email Subjects with Liquid

Liquid templating is supported in both the email body and the **Subject** line of any Mail Resource configured with Liquid mode. This enables personalized and localized subject lines tailored to user attributes, balances, or languages.

```liquid
{% if state.acc_real_balance > 0 %}
  Exclusive VIP Offer for {{ state.user_first_name }}!
{% else %}
  Welcome back, {{ state.user_first_name }}! Claim your bonus today
{% endif %}
```

### Frequently Asked Questions

**Q: How do I create a multilingual email using Liquid?**

A: You can branch content based on the player's language property using `state.core_user_language` (for example, `{% if state.core_user_language == 'ES' %}`). Do not use `label` tags inside Liquid conditionals, as label tags are evaluated after the Liquid engine runs.

**Q: How do I insert an unsubscribe link in a Liquid email?**

A: Use standard Smartico deep link syntax: `<a href="dp:unsubscribe">Unsubscribe</a>` or reference a label tag footer containing `dp:unsubscribe`. Do not use external template tags like `{% unsubscribe_url %}`, as unknown Liquid tags cause template compilation errors.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/crm-automation/communication-channels/liquid-email.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.