Elemental list element

The list element renders an ordered (numbered) or unordered (bulleted) list. Lists nest up to 5 levels deep. Parent and nested lists can each use their own loop. The type value is "list", and each child must be a "list-item" element. 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" }
      ]
    }
  ]
}

const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "list",
          list_type: "unordered",
          elements: [
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "First item",
                },
              ],
            },
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "Second item",
                },
              ],
            },
          ],
        },
      ],
    },
  },
});

response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "list",
            "list_type": "unordered",
            "elements": [
              {
                "type": "list-item",
                "elements": [
                  {
                    "type": "string",
                    "content": "First item",
                  },
                ],
              },
              {
                "type": "list-item",
                "elements": [
                  {
                    "type": "string",
                    "content": "Second item",
                  },
                ],
              },
            ],
          },
        ],
      },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "message": {
        "to": {
          "email": "sarah@acme-corp.com"
        },
        "content": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "list",
              "list_type": "unordered",
              "elements": [
                {
                  "type": "list-item",
                  "elements": [
                    {
                      "type": "string",
                      "content": "First item"
                    }
                  ]
                },
                {
                  "type": "list-item",
                  "elements": [
                    {
                      "type": "string",
                      "content": "Second item"
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "list",
          list_type: "unordered",
          elements: [
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "First item"
                }
              ]
            },
            {
              type: "list-item",
              elements: [
                {
                  type: "string",
                  content: "Second item"
                }
              ]
            }
          ]
        }
      ]
    }
  }
)

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "list",
      "list_type": "unordered",
      "elements": [
        {
          "type": "list-item",
          "elements": [
            {
              "type": "string",
              "content": "First item"
            }
          ]
        },
        {
          "type": "list-item",
          "elements": [
            {
              "type": "string",
              "content": "Second item"
            }
          ]
        }
      ]
    }
  ]
}`))

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{OfElementalContent: &content},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "list",
                    "list_type", "unordered",
                    "elements", java.util.List.of(
                      java.util.Map.of(
                        "type", "list-item",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "string",
                            "content", "First item"))),
                      java.util.Map.of(
                        "type", "list-item",
                        "elements", java.util.List.of(
                          java.util.Map.of(
                            "type", "string",
                            "content", "Second item")))))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'list',
          'list_type' => 'unordered',
          'elements' => [
            [
              'type' => 'list-item',
              'elements' => [
                [
                  'type' => 'string',
                  'content' => 'First item',
                ],
              ],
            ],
            [
              'type' => 'list-item',
              'elements' => [
                [
                  'type' => 'string',
                  'content' => 'Second item',
                ],
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);

// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "list",
                  "list_type": "unordered",
                  "elements": [
                    {
                      "type": "list-item",
                      "elements": [
                        {
                          "type": "string",
                          "content": "First item"
                        }
                      ]
                    },
                    {
                      "type": "list-item",
                      "elements": [
                        {
                          "type": "string",
                          "content": "Second item"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
            """)),
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "list", "list_type": "unordered", "elements": [{"type": "list-item", "elements": [{"type": "string", "content": "First item"}]}, {"type": "list-item", "elements": [{"type": "string", "content": "Second item"}]}]}]}'

With Courier MCP, send an email to sarah@acme-corp.com listing every item in their order.

Fields

string

required

One of "ordered" (numbered) or "unordered" (bulleted).

ListItemElement[]

required

An array of list item elements. Each must be of type "list-item". See the List item fields section below.

string

Renders bullets as a custom image, for unordered lists only. The image URL becomes the bullet.

string

URL for the bullet image, if used. Makes the bullet image clickable.

string

An expression that generates the list from data. See .

string | object[]

A condition that determines whether the list renders. Accepts a string expression or a structured condition array. See .

string[]

An array of channel names. The list renders only for the listed channels. See .

List item fields Each item in the elements array must be a list item element with the following properties:

string

required

Must be "list-item".

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

string

Background color for the list item. Any valid CSS color value.

string

An expression that repeats the list item. See .

string | object[]

A condition that determines whether the list item renders. Accepts a string expression or a structured condition array. See .

Examples and 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" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

List items with links 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" }
      ]
    }
  ]
}

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

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Elemental list element