# How to add display conditions to your email?

From the Email Composer, display conditions can be added directly to the text blocks or structures that make up your templates.

These conditional blocks can be used to:

* **Define conditions for displaying text** based on user data
* **Create a loop displaying the different elements** present in an **object array**
* **Reference data from a** [**Catalog**](https://app.gitbook.com/s/UIK868wiiK9XOVyETGZS/features/customer-engagement-platform/profiles/catalogs) to enrich your email with external data

{% hint style="danger" %}
Conditional blocks can only be activated on **template structures**.
{% endhint %}

## Conditional Block <a href="#h_2efb285f9a" id="h_2efb285f9a"></a>

To activate and add a condition to a structure:

1. Click on the **Edit email** button in your campaign and then select the structure to which you want to apply the condition.
2. In the menu on the left, click on **Conditions**
3. Activate the toggle button **Apply Display Conditions**

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FHFtR8pFjKAkzJfqfEmqD%2FCleanShot%202025-01-20%20at%2017.59.05%402x.png?alt=media&#x26;token=51eada38-da45-43d1-ad9c-43111748eed3" alt=""><figcaption></figcaption></figure>

A list of elements to fill in will then appear:

1. **Name&#x20;*****(Required)*****:** Name of the condition *(ex: display cart news items)*
2. **Description (*****Optional*****)**: Description of the condition
3. **Code before module**: Beginning of the condition *(ex: {% if ... %})*
4. **Code after module**: End of condition *(ex: {% endif %})*

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2Fzb4YQDIlnAVaw6j31VzY%2FCleanShot%202025-01-20%20at%2018.00.12%402x.png?alt=media&#x26;token=1d8c0cfb-4002-4e08-aa7a-d7b1dbf0007d" alt=""><figcaption></figcaption></figure>

You can use the **same condition on several structures**, use the same name and the other elements will be filled in automatically.

In the case of a condition in a text block, the `>` and `<` symbols are not supported on the Email Composer.

{% hint style="danger" %}
**Modifying any element of the condition other than its name will modify all the conditions with the same name.**
{% endhint %}

***

## Type of conditions & data <a href="#h_2d473cf1a6" id="h_2d473cf1a6"></a>

### Conditions <a href="#h_93b935ec52" id="h_93b935ec52"></a>

There are two possible types of condition, **if** and **for**:

#### if (only if) <a href="#h_5805b72cc1" id="h_5805b72cc1"></a>

These conditions allow a structure to be displayed or not, depending on the value of a user attribute or an event attribute.

For example, if you want to condition the display of your structure based on a `boolean` attribute indicating whether or not the user has a premium account:

> **Code before module**
>
> `{% if is_premimum == true %}` or `{% if trigger_event.is_premimum == true %}` *(if the attribute is attached to the trigger event)*

> **Code after module**
>
> `{% endif %}`

Several types of logical operators can be used in if conditions to compare the value of a user attribute:

* `==`: equal to
* `!=`: not equal to
* `>`: strictly greater than
* `<`: strictly less than
* `=`: greater than or equal to
* `<=`: less than or equal to

{% hint style="info" %}
You can also [combine comparisons easily](https://doc.batch.com/getting-started/features/customer-engagement-platform/message/personalization#combining-comparisons) in **if** conditions, with **AND** and **OR.**
{% endhint %}

#### if, else <a href="#h_9c62a43f2f" id="h_9c62a43f2f"></a>

The if and else structures can be used to manage **a case and its opposite**. If the if condition is satisfied, the first block of code is executed; otherwise, the else block is executed.

For example, if you want to display a different structure depending on a customer attribute indicating a promotion:

Block 1 (condition met):

> **Code before module**
>
> `{% if has_discount == true %}`

> **Code after module**
>
> *`No code`*

Block 2 (condition not met):

> **Code before module**
>
> `{% else %}`

> **Code after module**
>
> `{% endif %}`

It is also possible to link several if-else loops together to handle more complex cases:

Block 1 (condition 1 met):

> **Code before module**
>
> `{% if condition1 == true %}`

> **Code after module**
>
> *`No code`*

Block 2 (condition 1 not met, condition 2 met):

> **Code before module**
>
> `{% else if condition2 == true %}`

> **Code after module**
>
> *`No code`*

Block 3 (condition 1 and 2 not met):

> **Code before module**
>
> `{% else %}`

> **Code after module**
>
> `{% endif %}`

#### for (loop) <a href="#h_25e31f0905" id="h_25e31f0905"></a>

These conditions are used to retrieve data from object arrays. They will browse all the data present in all the objects in the array to display them in your structure.

For example, if you want to display the product information linked to the `add_to_cart` event, in the case where the array of objects has the name `article_infos`:

> **Code before module**
>
> `{% for $item in trigger_event.article_infos %}`
>
> * `$item`: Iteration variable you create that retrieves data from the object array for display on your structure in this way: `item.product_name`
> * `trigger_event.article_infos`: Indicates the name of the array of objects attached to the trigger event in which the data you want to retrieve can be found.

> **Code after module**
>
> `{% endfor %}`

### Data <a href="#h_453f72ad40" id="h_453f72ad40"></a>

There are three types of user data and one type of non-user centric data:

* [Strings array](https://doc.batch.com/getting-started/features/mobile-engagement-platform/push/message-personalization/advanced#filters-for-tag-collections-only) `[]`: Formerly called Tag collections, arrays can contain only a list of strings (`String`). You can only display:
  * All elements present in the array: `{{ c.interests }}`
  * The first element: `{{ c.interests|first }}`
  * The last element: `{{ c.interests|last }}`
* Object `{}`: Objects make it possible to group several pieces of information that are linked in a single piece of user data together.

  For example, a user's address will no longer be divided into three string attributes (*street, zipcode, city*):

```
address : { 
"city":"Paris",
"zip_code":"75003",
"street":"43 rue Beaubourg" 
}
```

You can refer to object properties using the following notation:

*You live in `{{ address.street }}`, `{{ address.zip_code }}`* *`{{ address.city }}`*

* **Object array** `[ {} ]`: Object arrays are simply a list of objects. **An array of objects can have up to three levels of nesting**, i.e. an array of objects can contain an array of objects which itself contains an array of objects.

{% hint style="warning" %}
Data in arrays of objects can only be accessed using a **for loop**.

The for loop will display all the objects in the array: it is not possible to choose which object to display.
{% endhint %}

This type of data is often found for retail customers attached to purchase validation or order confirmation events.

Here is an example of a table of purchase validation objects containing two products:

```
articles :[ 
  { 
    "name":"Lord of the Rings",
    "category":"film",
    "price":14.99, 
    "quantity":1, 
  }, 
  {
    "name":"Brol Vinyle - Angèle", 
    "category":"music", 
    "price":31.99, 
    "quantity":1, 
  } 
]

```

* **Catalog data**: Catalogs allow you to reference external data that is not stored on the user profile or in the trigger event, such as product details, store information, or editorial content. You need to have your data stored in a [Catalog](https://app.gitbook.com/s/UIK868wiiK9XOVyETGZS/features/customer-engagement-platform/profiles/catalogs) first. You can then fetch an item using the `lookup` function, which takes two arguments: the **catalog name** and the **item ID**. The item ID can be a profile attribute, a trigger event attribute, or a static value:

  * From a profile attribute: \
    `{% set $vehicle = lookup('vehicle_catalog', favorite_vehicle_id) %}`
  * From a trigger event attribute:\
    `{% set $vehicle = lookup('vehicle_catalog', trigger_event.vehicle_id) %}`
  * From a static value:\
    `{% set $vehicle = lookup('vehicle_catalog', '3554') %}`

  Once fetched, access any of the item's attributes: `{{ $vehicle.brand }}`, `{{ $vehicle.model }}`, `{{ $vehicle.price }}`

{% hint style="info" %}
The `lookup` is usually placed in the **Code before module**. The **Code after module** can be left empty. It can also be written directly in the text of your template.
{% endhint %}

***

## Some examples <a href="#h_225c649227" id="h_225c649227"></a>

### Display condition for a block (if) <a href="#h_c2c95b8634" id="h_c2c95b8634"></a>

#### Boolean <a href="#h_7d5dfaa858" id="h_7d5dfaa858"></a>

Here is an example of a case where you want to display a block if the user is premium.

**Context**

There is an `is_premium` attribute attached to the user profile and you want to display the block if the value of this attribute is equal to `true`:

> **Code before module**
>
> There are several options:
>
> * Option 1: `{% if is_premium %}`
> * Option 2: `{% if is_premium == true %}`

> **Code after module**
>
> `{% endif %}`

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FGbjlwTdLWJrAAWTs5cVc%2FScreenshot%202025-01-07%20at%2009.36.26.png?alt=media&#x26;token=596119fb-4e41-4a36-9962-1bba67e467a4" alt=""><figcaption></figcaption></figure>

#### String <a href="#h_e6a5187a3f" id="h_e6a5187a3f"></a>

Let's imagine that you want to display a block based on the user's region.

**Context**

You offer different baskets depending on the user's region, and the display depends on the value of the custom `region_fr` attribute:

> **Code before module**
>
> `{% if region_fr =='Région Auvergne-Rhône-Alpes’ %}`

> **Code after module**
>
> `{% endif %}`

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FzulKRfpWDWtSCQZroB5o%2FScreenshot%202025-02-27%20at%2014.48.58.png?alt=media&#x26;token=94f566f7-08ae-4d80-9ede-265976db2f76" alt=""><figcaption></figcaption></figure>

#### Integer <a href="#h_41f2c01f13" id="h_41f2c01f13"></a>

Here, you want to display a block according to the number of loyalty points a user has.

**Context**

The `fid_points` attribute is of type `int` and you want to display the block if the user has more than 500 loyalty points:

> **Code before module**
>
> `{% if fid_points >= 500 %}`

> **Code after module**
>
> `{% endif %}`

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FTGZQWLPLzYy8oV9zzUZL%2FScreenshot%202025-01-07%20at%2010.00.43.png?alt=media&#x26;token=9c41bdb9-69a6-495c-b577-7be891f9bd35" alt=""><figcaption></figcaption></figure>

### Array of string *(formerly Tag Collections)* <a href="#h_d06fe148a4" id="h_d06fe148a4"></a>

Let's say you want to display a block based on the values in an array of strings *(tag collections)*.

**Context**

You sell trackers for animals and a single customer can have several animals and therefore several trackers. You want to display the block if the string array `favorite_category` contains ‘`hats`’ or ‘`sunglasses`’:

> **Code before module**
>
> `{% if t.favorite_category|contains('hats')` or `t.favorite_category|contains('sunglasses')%}`

> **Code after module**
>
> `{% endif %}`

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FQAx1mrysVZUXa1D78zbv%2FScreenshot%202025-02-27%20at%2014.58.04.png?alt=media&#x26;token=ee51def3-6df8-46be-bd80-b01e6aaa8bc1" alt=""><figcaption></figcaption></figure>

### Condition for displaying a complex block (if, else if, else) <a href="#h_bb384c693b" id="h_bb384c693b"></a>

If you want to send an email containing a single piece of information, but adapted according to several conditions without making it too complicated to manage, using an **if, else if, else block** is ideal.

Let's imagine you want to send a personalized email to your customers, offering them trips based on their last trip or, failing that, their age:

Block 1:

> **Code before module**
>
> `{% if last_purchased_trip == 'mountain' %}`

> **Code after module**
>
> *`No code`*

Block 2:

> **Code before module**
>
> `{% else if last_purchased_trip == 'beach' %}`

> **Code after module**
>
> *`No code`*

Block 3:

> **Code before module**
>
> `{% else if age >= 30 %}`

> **Code after module**
>
> *`No code`*

Block 4:

> **Code before module**
>
> `{% else %}`

> **Code after module**
>
> `{% endif %}`

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FJJ9edjm0qEHUAkO4RuoB%2Fscreenshot5.png?alt=media&#x26;token=64627038-a8ec-4261-bc7b-7408e408447a" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
This ensures that a single block is displayed while **maintaining a flexible structure.**

Adding a new condition, whether it relates to the same attribute or another, can be done without impacting the existing conditions.
{% endhint %}

### Catalog personalization <a href="#h_catalog_personalization" id="h_catalog_personalization"></a>

#### **Fetching a catalog item**

Here, let's say you want to display information about a vehicle from your `vehicle_catalog` catalog.

The user profile has a `favorite_vehicle_id` attribute that contains the ID of an item in the catalog.

**Conditions:**

> **Code before module**
>
> `{% set $vehicle = lookup('vehicle_catalog', favorite_vehicle_id) %}`

> **Code after module**
>
> *Can be left empty*

**Data display in the template:**

`{{ $vehicle.brand }}` `{{ $vehicle.model }}` — `{{ $vehicle.price }}` €

#### **Chained lookups (multi-catalog)**

A catalog item can contain a reference to an item in **another catalog**. You can chain multiple `lookup` calls.

Let's say you have a `weekly_schedule` catalog where each entry contains a `show_id` field that references an item in a separate `shows` catalog.

**Conditions:**

> **Code before module**
>
> * `{% set $schedule = lookup('weekly_schedule', 'monday_prime') %}`\
>   `{% set $show = lookup('shows', $schedule.show_id) %}`

> **Code after module**
>
> *Can be left empty*

**Data display in the template:**

`{{ $schedule.air_time }}` — `{{ $show.title }}`

`{{ $show.synopsis }}`

#### **Multiple items in a single structure**

You can fetch several catalog items at once to display them side by side in the same structure, for example, a row of recommended products.

Let's say you want to display 3 products from your `products` catalog. The user profile has three attributes: `recommended_1`, `recommended_2`, and `recommended_3`, each containing a catalog item ID.

**Conditions:**

> **Code before module**
>
> * `{% set $product_1 = lookup('products', recommended_1) %}`

> * `{% set $product_2 = lookup('products', recommended_2) %}`

> * `{% set $product_3 = lookup('products', recommended_3) %}`

> **Code after module**
>
> *Can be left empty*

**Data display in the template:**

| Column 1                   | Column 2                   | Column 3                   |
| -------------------------- | -------------------------- | -------------------------- |
| `{{ $product_1.name }}`    | `{{ $product_2.name }}`    | `{{ $product_3.name }}`    |
| `{{ $product_1.price }}` € | `{{ $product_2.price }}` € | `{{ $product_3.price }}` € |

### Object personalization loop <a href="#h_a65f896899" id="h_a65f896899"></a>

The following use cases have been implemented for transactional email automations. These templates combine **conditions** and **object personalization loops**.

#### A single level of nesting <a href="#h_6d7b2d6154" id="h_6d7b2d6154"></a>

Here, let's say you want to display the list of items canceled for the user's order as follows:

`{{item name}}` x `{{item quantity}}`       `{{item price}}`€

**Conditions:**

> **Code before module**
>
> `{% for $articles in trigger_event.order %}`

> **Code after module**
>
> `{% endfor %}`

**Data display in the template:**

`{{$articles.product_name}}` x `{{$articles.quantity}}` `{{$articles.total_price}}`€

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FMkL8yR8KQgL0fQkXqPFc%2FCleanShot%202025-03-06%20at%2014.33.00%402x.png?alt=media&#x26;token=9773a9e2-5eca-4e01-a519-3dc4d375d77a" alt=""><figcaption></figcaption></figure>

#### Two levels of nesting <a href="#h_1c5f2a0951" id="h_1c5f2a0951"></a>

Here is an example of an order validation email automation, which is based on the `validated_order` event composed of an array of objects with two levels of nesting:

* **1st level**: array of `orders` objects containing order information
* **2nd level**: array of `product` objects containing product information

Here, orders can be split up at different times, as the products ordered by a user can be sent by several shippers. In the case of multiple shippers, you would like the orders to be sent one after the other.

{% hint style="success" %}
Split command: `is_splitted` attribute set to `true`
{% endhint %}

The template will contain two structures, the first with the order information and the second with the products in the orders. As a result, the **display condition will be spread over both structures.**

**1st structure**

> **Code before module**
>
> * `{% if trigger_event.is_splitted %}`
> * `{% for $order in trigger_event.orders %}` *(we browse the array of orders)*

> **Code after module**
>
> *`No code`*

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2Fb2HAcKUURktsoIqHYbTd%2FCleanShot%202025-03-06%20at%2014.42.39%402x.png?alt=media&#x26;token=5951f3f8-2020-4078-9e5d-2fe649f6e104" alt=""><figcaption></figcaption></figure>

**2nd structure**

> **Code before module**
>
> `{% for $articles in $order.product %}` *(we browse the array of lines objects present in the array of orders objects)*

> **Code after module**
>
> * `{% endfor %}` *(closes the for loop initialized in the 2nd structure)*
> * `{% endfor %}` *(closes the for loop initialized in the 1st structure)*
> * `{% endif %}` *(closes the if condition initialized in the 1st structure)*<br>

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2Fp8K4vM8IVLKKaUV6Ea5l%2FCleanShot%202025-03-06%20at%2014.44.50%402x.png?alt=media&#x26;token=96b4ebd0-3aa0-47b7-9817-6fe5ed35135d" alt=""><figcaption></figcaption></figure>

***

## Testing the conditions <a href="#h_1af58b37e3" id="h_1af58b37e3"></a>

To test your display conditions in real conditions, you can click on your email, select ‘...’ then **Preview as**:&#x20;

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FcTQK5VEFrwebgrnbQDuh%2FCleanShot%202025-02-04%20at%2013.14.18%402x.png?alt=media&#x26;token=16d21202-c364-4d19-9662-4c56fe62bfc2" alt=""><figcaption></figcaption></figure>

Then **add a Custom ID** and click on **Update preview**:

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FoMYsirTUqn1vl7INKYSm%2FCleanShot%202025-02-04%20at%2013.19.31%402x.png?alt=media&#x26;token=e4510970-ec9e-44c1-9dbc-40b3400aec31" alt=""><figcaption></figcaption></figure>

The content of your email will appear with the user's personal details instead of the conditions.

{% hint style="danger" %}
Note that the email address you want to preview **must be associated with a profile that has values** for the conditions to be tested.
{% endhint %}

You can then test how the email looks, by using the **Send test** button on the email message window and typing your email address:

<figure><img src="https://509463063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfiAYaWDWqtFZeXxyg67F%2Fuploads%2FPNEkcigHQyyixHSEYgAK%2FCleanShot%202025-02-04%20at%2013.37.44%402x.png?alt=media&#x26;token=d9ee8148-a9f2-4475-9563-421bb090c2ae" alt=""><figcaption></figcaption></figure>

The email is immediately sent, with the right conditions applied! ✨