> For the complete documentation index, see [llms.txt](https://doc.batch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.batch.com/guides-and-best-practices/message/email/personalization-and-display-logic/how-to-add-display-conditions-to-your-email.md).

# How to add display conditions to your email?

From the Email Composer, display conditions can be added to **email blocks** (template structures) so each recipient only sees the blocks that match their profile or trigger event data.

These conditional blocks can be used to:

* **Show or hide a block** based on profile or trigger event attributes
* **Create a loop** over an **object array**
* **Reference data from a** [**Catalog**](/getting-started/features/customer-engagement-platform/profiles/catalogs.md) to enrich your email with external data

{% hint style="danger" %}
Display conditions apply to **email blocks only**. They cannot be used for inline personalization inside block text.
{% endhint %}

{% hint style="info" %}
**What's new:** Display conditions are now configured in a guided **Add conditional block** modal. Simple **if** conditions can be built visually, no code required for common cases. Advanced logic is still available via **Code** mode.
{% endhint %}

***

### Add a conditional block <a href="#h_2efb285f9a" id="h_2efb285f9a"></a>

To add or edit a condition on a block:

1. Open your campaign and click **Edit email**.
2. In the editor, select the **block** (structure) you want to condition.
3. Open display conditions using either:

* The **Display** **Conditions** icon on the structure:&#x20;

<figure><img src="/files/sReUjVInhuezA0Yg6zoi" alt=""><figcaption></figcaption></figure>

* The **Display Conditions** button in the right-hand panel:&#x20;

<figure><img src="/files/hjWlE3jNdxVfGZDmrSU8" alt=""><figcaption></figcaption></figure>

4. The **Add conditional block** modal opens:&#x20;

<figure><img src="/files/G9CGN7Eq8bagRyZLy8Is" alt=""><figcaption></figcaption></figure>

#### Visual editor (recommended)

By default, the modal opens on the visual editor. From there:

* Pick a **profile attribute** or **trigger event attribute** (for transactional emails).

<figure><img src="/files/WONEAKA72UvGPF6deKzj" alt=""><figcaption></figcaption></figure>

* Choose an **operator** and a **value**. Indexed values are selectable where available, no need to type attribute values from memory.
* Combine rules with **AND** / **OR** and **subgroups** for more complex logic.
* **Country** and **Language** are available as dedicated attributes.
* Click **Save conditions** when done.

<figure><img src="/files/TBFV572edmFHv1eVOuG0" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The visual editor supports **if** conditions only. For `else`, `else if`, `for` loops, catalog lookups, and other advanced logic, use **Code mode**.
{% endhint %}

#### Code mode (advanced)

Use Code mode when the visual editor cannot express your logic:

1. In the modal, click **Convert to code** or **Or create with code** from the empty state.
2. Fill in the **Before block** and **After block** fields.
3. Click **Save conditions**.

<figure><img src="/files/hI3s0wZzHmTXyh8CihtL" alt=""><figcaption></figcaption></figure>

***

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

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

There are two main condition types: **if** and **for**. Simple **if** rules can be built in the visual editor; **for**, **else**, and **else if** require Code mode.

**if (only if)**

These conditions show or hide a block depending on the value of a profile attribute, a trigger event attribute, or a built-in attribute (e.g. country, language).

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

> **Before block**
>
> `{% if is_premium %}` or `{% if is_premium == true %}`

> **After block**
>
> `{% endif %}`

For trigger event attributes, use the `trigger_event` prefix, e.g. `{% if trigger_event.is_premium == true %}`.

Several comparison operators are available:

* `==`: 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** in the visual editor via subgroups, or in Code mode.
{% endhint %}

**if, else**

The **if / else** structure manages a case and its opposite. This requires **Code mode** across multiple blocks.

For example, to display a different block depending on whether a customer has a discount:

Block 1 (condition met):

> **Before block:** `{% if has_discount == true %}`

> **After block:** *No code*

Block 2 (condition not met):

> **Before block:** `{% else %}`

> **After block:** `{% endif %}`

It is also possible to chain several **if / else if / else** blocks to handle more complex cases:

Block 1:

> **Before block:** `{% if condition1 == true %}` — **After block:** *No code*

Block 2:

> **Before block:** `{% else if condition2 == true %}` — **After block:** *No code*

Block 3:

> **Before block:** `{% else %}` — **After block:** `{% endif %}`

**for (loop)**

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** loops iterate over object arrays to display all items in a structure. They are only available in **Code mode**.

For example, to display product information from an `add_to_cart` event where the object array is named `article_infos`:

> **Before block**
>
> `{% for $item in trigger_event.article_infos %}`

> **After block**
>
> `{% endfor %}`

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

* [**Strings array**](https://doc.batch.com/getting-started/features/mobile-engagement-platform/push/message-personalization/advanced#filters-for-tag-collections-only) `[]` (tag collections): display all elements (`{{ c.interests }}`), the first (`{{ c.interests|first }}`), or the last (`{{ c.interests|last }}`). In the visual editor, use **contains** / **does not contain** operators on tag attributes.
* **Object** `{}`: groups related fields; access with dot notation, e.g. `{{ address.street }}`.

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** `[ {} ]`: a list of objects, up to **three levels of nesting**. Data is accessed with a **for** loop (Code mode).

{% hint style="warning" %}
Data in object arrays can only be accessed using a **for loop**. The loop displays all objects in the array, it is not possible to select a single item by index.
{% 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 not stored on the user profile or trigger event. Use the `lookup` function with the catalog name and item ID. The ID can come from a profile attribute, a trigger event attribute, or a static value:&#x20;
  * 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 **Before block**. The **After block** 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>

Unless noted, the examples below can be built directly in the **visual editor**.

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

{% hint style="warning" %}
**Code mode only:** split across multiple blocks as described in the if, else section.
{% endhint %}

If you want to send an email with content adapted to several conditions, an **if / else if / else** structure is ideal.

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

Block 1: `{% if last_purchased_trip == 'mountain' %}` — *no after code*

Block 2: `{% else if last_purchased_trip == 'beach' %}` — *no after code*

Block 3: `{% else if age >= 30 %}` — *no after code*

Block 4: `{% else %}` — `{% endif %}`

{% 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 existing conditions.
{% endhint %}

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

{% hint style="warning" %}
**Code mode only**
{% endhint %}

**Fetching a catalog item**

Let's say you want to display vehicle information from your `vehicle_catalog`. The user profile has a `favorite_vehicle_id` attribute containing the ID of the item to fetch.

> **Before block:** `{% set $vehicle = lookup('vehicle_catalog', favorite_vehicle_id) %}`

> **After block:** *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.

For example, a `weekly_schedule` catalog where each entry contains a `show_id` referencing a separate `shows` catalog:

> **Before block:**
>
> `{% set $schedule = lookup('weekly_schedule', 'monday_prime') %}`

> `{% set $show = lookup('shows', $schedule.show_id) %}`

> **After block:** *Can be left empty*

**Data display in the template:** `{{ $schedule.air_time }}` — `{{ $show.title }}`

**Multiple items in a single structure**

You can fetch several catalog items at once to display them side by side: for example, a row of recommended products. The user profile has three attributes (`recommended_1`, `recommended_2`, `recommended_3`) each containing a product ID.

> **Before block:**
>
> `{% set $product_1 = lookup('products', recommended_1) %}`

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

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

> **After block:** *Can be left empty*

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

{% hint style="warning" %}
**Code mode only**
{% endhint %}

**A single level of nesting**

Here, let's say you want to display the list of items in a user's order:

> **Before block:** `{% for $articles in trigger_event.order %}`

> **After block:** `{% endfor %}`

**Data display in the template:** `{{ $articles.product_name }}` x `{{ $articles.quantity }}` `{{ $articles.total_price }}`€

**Two levels of nesting**

Here is an example of an order validation email based on a `validated_order` event with two levels of nesting:

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

Orders can be split across different shippers. The display condition spans **two structures**.

**1st structure**

> **Before block:**
>
> `{% if trigger_event.is_splitted %}`

> `{% for $order in trigger_event.orders %}`

> **After block:** *No code*

**2nd structure**

> **Before block:** `{% for $articles in $order.product %}`

> **After block:**
>
> `{% endfor %}`

> `{% endfor %}`

> `{% endif %}`

***

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

To preview your display conditions with real data, click on your email, select **Preview as**:

<div align="left"><figure><img src="/files/XUuxefDvSgnye9Tia8Tc" alt=""><figcaption></figcaption></figure></div>

Then **add a Custom ID** and click **Update preview**:&#x20;

<figure><img src="/files/FANodYPfo8qvkjiyvTXu" alt=""><figcaption></figcaption></figure>

The email content will appear with the user's actual data applied instead of the raw conditions.

{% hint style="danger" %}
The profile you're previewing **must have values for the attributes** used in your conditions.
{% endhint %}

You can test the final rendering by clicking **Send test** from the email message window and entering your email address:

<figure><img src="/files/ku5A9jfLdXgJ9KPxIdbT" alt=""><figcaption></figcaption></figure>

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.batch.com/guides-and-best-practices/message/email/personalization-and-display-logic/how-to-add-display-conditions-to-your-email.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.