Elemental Markup Overview

Why Courier Elemental?

Courier Elemental is the single format behind every Courier template: one multichannel wrapper that holds content of any type. A template is a JSON list of content blocks (text, image, action, and more), or a raw payload like an HTML document, and Courier renders it across every channel you send on: email, push, SMS, inbox, and chat. Define the notification once, and Elemental adapts it per channel, locale, and recipient. For email, you can build with Elemental blocks or drop in a complete HTML document. See Providing email content for how the two forms differ and when to use each.

Elemental Capabilities

Courier Elemental supports adaptive, multi-channel notifications. Here’s a quick overview of the main capabilities:

Localization

Automatically serve content in your users’ preferred language using Elemental’s built-in locale system. Define translations once and Courier handles the rest based on the recipient’s locale.

{
  "type": "text",
  "content": "Welcome, {{user_name}}!",
  "locales": {
    "es": {
      "content": "¡Bienvenido, {{user_name}}!"
    },
    "fr": {
      "content": "Bienvenue, {{user_name}} !"
    }
  }
}

Learn more about localization in the Locales documentation.

Channel-Specific Customization

Customize your notification content for different channels using channel elements or the channels property. Send detailed emails and concise SMS from the same template structure. Using channel elements:

{
  "type": "channel",
  "channel": "email",
  "elements": [
    { "type": "text", "content": "Detailed email content..." }
  ]
},
{
  "type": "channel",
  "channel": "sms",
  "elements": [
    { "type": "text", "content": "Short SMS message" }
  ]
}

Using the channels property:

{
  "type": "text",
  "content": "This only appears in email and push",
  "channels": ["email", "push"]
}

Learn more about channel customization in the Control Flow documentation.

Dynamic Logic

Use conditional rendering, loops, and element references to create notifications that adapt to your data and user context. Conditional rendering with if:

{
  "type": "text",
  "content": "Premium feature available!",
  "if": "data.user_tier === 'premium'"
}

Iteration with loop:

{
  "type": "group",
  "loop": "data.products",
  "elements": [
    {
      "type": "text",
      "content": "{{$.item.name}} - {{$.item.price}}"
    }
  ]
}

Element references with ref:

{
  "type": "text",
  "content": "Hello",
  "ref": "greeting"
},
{
  "type": "text",
  "content": "This shows if greeting is visible",
  "if": "refs.greeting.visible"
}

Learn more about dynamic logic in the Control Flow documentation.

Where Elemental is Used

Elemental is the format everywhere content lives in Courier:

Stored templates: Templates are stored as Elemental. Edit them visually in Design Studio or Courier Create, or manage the same templates programmatically through the Templates API. The designer and the API read and write the same Elemental, so a template built in one is editable in the other. Design Studio wraps email content in a channel: email element.
Inline sends: Pass Elemental directly in a Send API request to send a one-off notification without storing a template.

Construct an Elemental Template

All Courier Elemental templates have the following top level structure. When used in API calls, this structure is passed as the content property of the message object:

{
  "version": "2022-01-01",
  "elements": [
    // CourierElement[]
  ]
}

In API calls, the Elemental template is nested under message.content:

{
  "message": {
    "to": { "email": "user@example.com" },
    "content": {
      "version": "2022-01-01",
      "elements": [
        // CourierElement[]
      ]
    }
  }
}

Required Fields

string

required

Specifies the Elemental format version. The only supported value at this time is "2022-01-01"

CourierElement[]

required

Array of Courier Elements. See the Elements Index for a complete reference of all available element types.

Understanding Elemental Structure

Elemental templates use a tree-like structure where elements can contain other elements. The elements array is the root container, and many element types support nested elements arrays of their own.

Element Nesting

Elements can be nested within other elements to create complex, hierarchical structures: Container elements that support nesting:

group - Groups elements together for conditional logic or loops
channel - Contains channel-specific element collections
columns - Contains column elements, which in turn contain their own elements
list - Contains list-item elements, which can contain text content or nested lists

Example of nested structure:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        {
          "type": "meta",
          "title": "Order Confirmation"
        },
        {
          "type": "group",
          "if": "data.items.length > 0",
          "elements": [
            {
              "type": "columns",
              "elements": [
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [
                    {
                      "type": "image",
                      "src": "{{item.image}}"
                    }
                  ]
                },
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [
                    {
                      "type": "text",
                      "content": "{{item.name}}"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

In this example:

The root elements array contains a channel element
The channel element contains its own elements array with meta and group elements
The group element contains a columns element
The columns element contains column elements
Each column contains its own elements array with image and text elements

Tree Structure Benefits

This hierarchical structure enables:

Logical grouping: Related elements can be grouped together
Conditional rendering: Entire groups can be shown or hidden based on conditions
Reusable patterns: Common element combinations can be encapsulated in groups
Channel customization: Different branches of the tree can target different channels
Complex layouts: Nested structures enable multi-column and grid layouts

For a complete reference of all available element types and their properties, see the Elements Index.

Example

A complete notification with a subject, banner image, body text, and a call to action:

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "user@example.com" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "meta",
            "title": "Welcome to {{company_name}}, {{user_name}}!"
          },
          {
            "type": "image",
            "src": "https://example.com/welcome-banner.jpg",
            "alt_text": "Welcome Banner"
          },
          {
            "type": "text",
            "content": "Hi {{user_name}}, we're excited to have you join us! Your account is now active and ready to use."
          },
          {
            "type": "action",
            "content": "Get Started",
            "href": "https://app.example.com/dashboard"
          }
        ]
      },
      "data": {
        "user_name": "Alex",
        "company_name": "Acme Corp"
      }
    }
  }'

const { requestId } = await courier.send.message({
  message: {
    to: { email: "user@example.com" },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "meta",
          title: "Welcome to {{company_name}}, {{user_name}}!"
        },
        {
          type: "image",
          src: "https://example.com/welcome-banner.jpg",
          alt_text: "Welcome Banner"
        },
        {
          type: "text",
          content: "Hi {{user_name}}, we're excited to have you join us! Your account is now active and ready to use."
        },
        {
          type: "action",
          content: "Get Started",
          href: "https://app.example.com/dashboard"
        }
      ]
    },
    data: {
      user_name: "Alex",
      company_name: "Acme Corp"
    }
  }
});

response = client.send.message(
  message=courier.ContentMessage(
    to=courier.UserRecipient(email="user@example.com"),
    content={
      "version": "2022-01-01",
      "elements": [
        {
          "type": "meta",
          "title": "Welcome to {{company_name}}, {{user_name}}!"
        },
        {
          "type": "image",
          "src": "https://example.com/welcome-banner.jpg",
          "alt_text": "Welcome Banner"
        },
        {
          "type": "text",
          "content": "Hi {{user_name}}, we're excited to have you join us! Your account is now active and ready to use."
        },
        {
          "type": "action",
          "content": "Get Started",
          "href": "https://app.example.com/dashboard"
        }
      ]
    },
    data={
      "user_name": "Alex",
      "company_name": "Acme Corp"
    }
  )
)

Platform

Developer Tools

Help

Elemental Markup Overview

Why Courier Elemental?

Elemental Capabilities

Localization

Channel-Specific Customization

Dynamic Logic

Where Elemental is Used

Construct an Elemental Template

Required Fields

Understanding Elemental Structure

Element Nesting

Tree Structure Benefits

Example

​Why Courier Elemental?

​Elemental Capabilities

​Localization

​Channel-Specific Customization

​Dynamic Logic

​Where Elemental is Used

​Construct an Elemental Template

​Required Fields

​Understanding Elemental Structure

​Element Nesting

​Tree Structure Benefits

​Example

Why Courier Elemental?

Elemental Capabilities

Localization

Channel-Specific Customization

Dynamic Logic

Where Elemental is Used

Construct an Elemental Template

Required Fields

Understanding Elemental Structure

Element Nesting

Tree Structure Benefits

Example