Skip to main content

​
Overview

The list element allows you to create ordered (numbered) or unordered (bulleted) lists in your notifications. Lists support nesting up to 5 levels deep, enabling complex hierarchical structures. Both parent and nested lists can independently use loops for dynamic content generation. When to use:
  • Display ordered sequences (steps, rankings)
  • Show unordered items (features, benefits, options)
  • Create nested hierarchical structures
  • Display dynamic lists from data (products, items, etc.)

​
Basic Example

{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "First item" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Second item" }
      ]
    }
  ]
}

​
Fields

​
type
string
required
The type of element. For list elements, this value must be "list".
​
list_type
string
required
The type of list. Can be "ordered" (numbered) or "unordered" (bulleted).
​
elements
ListItemElement[]
required
An array of list item elements. Each element must be of type "list-item". See the List Item Fields section below.
​
imgSrc
string
Allows bullets to be rendered using a custom image (for unordered lists only). The image URL will be used as the bullet point.
​
imgHref
string
URL for the bullet image, if used. Makes the bullet image clickable.
​
loop
string
An expression that allows the list to be dynamically generated from data. See Control Flow documentation for details.
​
if
string
A condition that determines whether the list should be rendered. See Control Flow documentation for details.
​
channels
string[]
An array of channel names. The list will only be rendered for the specified channels. See Control Flow documentation for details.

​
List Item Fields

Each item in the elements array must be a list item element with the following properties:
​
type
string
required
The type of element. For list items, this value must be "list-item".
​
elements
CourierElement[]
required
Content of the list item. Can include:
  • string elements for text
  • link elements for clickable links
  • img elements for inline images
  • Nested list elements for sub-lists
​
background_color
string
Background color for the list item. Can be any valid CSS color value.
​
loop
string
An expression that allows the list item to be repeated. See Control Flow documentation for details.
​
if
string
A condition that determines whether the list item should be rendered. See Control Flow documentation for details.

​
Examples & Variants

​
Unordered List

Simple bulleted list: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 1" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 2" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Feature 3" }
      ]
    }
  ]
}

​
Ordered List

Numbered list: 
{
  "type": "list",
  "list_type": "ordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 1: Sign up" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 2: Verify email" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Step 3: Get started" }
      ]
    }
  ]
}

​
Nested Lists

Lists can be nested up to 5 levels deep: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Fruits" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Apple" }
              ]
            },
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Banana" }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Vegetables" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "elements": [
                { "type": "string", "content": "Carrot" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
Include clickable links in list items: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "View our " },
        { "type": "link", "content": "documentation", "href": "https://example.com/docs" },
        { "type": "string", "content": " for more info" }
      ]
    }
  ]
}

​
Dynamic Lists with Loops

Generate lists from data: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "loop": "data.products",
      "elements": [
        { "type": "string", "content": "{{$.item.name}} - ${{$.item.price}}" }
      ]
    }
  ]
}

​
Nested Dynamic Lists

Dynamic lists with nested loops: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "loop": "data.categories",
      "elements": [
        { "type": "string", "content": "{{$.item.name}}" },
        {
          "type": "list",
          "list_type": "ordered",
          "elements": [
            {
              "type": "list-item",
              "loop": "$.item.products",
              "elements": [
                { "type": "string", "content": "{{$.item}}" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

​
Custom Bullet Images

Use custom images for bullets: 
{
  "type": "list",
  "list_type": "unordered",
  "imgSrc": "https://example.com/custom-bullet.png",
  "imgHref": "https://example.com",
  "elements": [
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Item with custom bullet" }
      ]
    }
  ]
}

​
Styled List Items

List items with background colors: 
{
  "type": "list",
  "list_type": "unordered",
  "elements": [
    {
      "type": "list-item",
      "background_color": "#f0f0f0",
      "elements": [
        { "type": "string", "content": "Highlighted item" }
      ]
    },
    {
      "type": "list-item",
      "elements": [
        { "type": "string", "content": "Regular item" }
      ]
    }
  ]
}

​
Best Practices

  • Use appropriate list types: Use ordered lists for sequences (steps, rankings) and unordered lists for collections (features, options)
  • Limit nesting depth: While 5 levels are supported, 2-3 levels are usually sufficient for readability
  • Keep items concise: Long list items can be hard to scan
  • Use loops for dynamic content: Generate lists from data rather than hardcoding items
  • Consider mobile: Long lists may need special formatting for mobile devices
Lists can be nested up to 5 levels deep. Nested lists can have different list types (ordered/unordered) than their parent lists.

​
Channel Support

  • Email: ✅ Full support with proper list rendering
  • Push: ✅ Supported (may render as plain text in some cases)
  • SMS: ⚠️ Limited support (may render as plain text)
  • Inbox: ✅ Full support