Elements

This page provides a comprehensive reference for all available element types, their properties, and usage patterns.

Elemental Sugar

Syntactic Sugar to provide a fast shorthand for Courier Elemental Blocks.

Fields

Field	Type	Required	Description
title	string		The title to be displayed by supported channels i.e. push, email (as subject)
body	string	required	The text content displayed in the notification.

Example

Elemental Sugar does not require the use of message.content.version nor does it require nesting block objects in message.content.elements. Instead, simply pass Elemental Sugar properties directly under message.content:

{
  "message": {
    // ... rest of message,

    "content": {
      "title": "Hello",
      "body": "World"
    }
  }
}

Elemental Sugar can be used alongside Elemental blocks:

{
  "message": {
    // ... rest of message,

    "content": {
      "title": "Hello",
      "body": "World",
      "version": "2020-01-01",
      "elements": [
        // Courier Elemental Blocks
      ]
    }
  }
}

Action Element

Allows the user to execute an action. Can be a button or a link.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For action elements, this value should be action.
content	string	required	The text content of the action shown to the user.
href	string	required	The target URL of the action.
action_id	string		A unique id used to identify the action when it is executed.
align	string		The alignment of the action button. One of center, left, right, or full. Defaults to center.
background_color	string		The background color of the action button.
style	string		Can be button or link. Defaults to button.
locales	object		Region specific content. See locales docs for more details.

Example

Basic usage:

{
  "type": "action",
  "content": "Click me",
  "href": "https://example.com"
}

Channel Element

The channel element allows a notification to be customized based on which channel it is sent through. For example, you may want to display a detailed message when the notification is sent through email, and a more concise message in a push notification.

Channel elements are only valid as top-level elements; you cannot nest channel elements. If there is a channel element specified at the top-level of the document, all sibling elements must be channel elements.

Note: As an alternative, most elements support a channel property. Which allows you to selectively display an individual element on a per channel basis. See the control flow docs for more details.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For channel elements, this value should be channel.
channel	string	required	The channel the contents of this element should be applied to. Can be email, push, direct_message, sms or a provider such as slack
elements	CourierElement[]		An array of elements to apply to the channel. If raw has not been specified, elements is required.
raw	object		Raw data to apply to the channel. See example. If elements has not been specified, raw is required.

Example

Basic Usage:

{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "meta",
      "title": "My Subject"
    },
    {
      "type": "text",
      "content": "My email body"
    }
  ]
},
{
  "type": "channel",
  "channel": "default", // all other channels
  "elements": [
    {
      "type": "meta",
      "title": "My Title"
    },
    {
      "type": "text",
      "content": "Hello **world**"
    }
  ]
}

With raw:

// Email
{
  "type": "channel",
  "channel": "email",
  "raw": {
    "subject": "My Subject",
    "html": "<mjml>...</mjml>",
    "text": "Lorem ipsum dolor, sit amet", // Supports Markdown
    "transformers": ["handlebars", "mjml"] // Parameter for templating engine.
  }
},

// Slack
{
  "type": "channel",
  "channel": "slack",
  "raw": {
    "slackBlocks": { ... } // Block Kit
  }
},

// Webhook
{
  "type": "channel",
  "channel": "webhook",
  "raw": {
    "payload": {
      "body": {
        "hello": "world"
      }
    }
  }
}

Comment Element

The Comment element allows you to include comments in your Elemental structure that won't be rendered in the final output.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For comment elements, this value should be comment.
comment	string		The comment text.
object	any		An optional object that can be included with the comment.

Example

{
  "type": "comment",
  "comment": "This is a comment that won't be rendered in the output"
}

## Divider Element

Renders a dividing line between elements.

### Fields

| Field | Type   | Required | Description                                                                  |
| ----- | ------ | -------- | ---------------------------------------------------------------------------- |
| type  | `string` | required | The type of element. For divider elements, this value should be `divider`. |
| color | `string` |          | The CSS color to render the line with. I.E. `#fff`.                          |

### Example

```json
{
  "type": "divider",
  "color": "#800080"
}

Group Element

Allows you to group elements together. This can be useful when used in combination with if or loop. See control flow docs for more details.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For group elements, this value should be group.
elements	CourierElement[]	required	Sub elements to render.

Example

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

HTML Element

The HTML element allows you to include raw HTML content in your notification.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For image elements, this value should be image.
content	string	required	The raw HTML content to be included in the notification.
locales	string		Region specific content. See locales doc for more details.

Example

{
  "type": "html",
  "content": "<h1>Hello,<strong>World!</strong></h1>"
}

Image Element

Used to embed an image into the notification.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For image elements, this value should be image.
src	string	required	The source of the image.
align	string		The alignment of the image. One of center, left, right, or full.
alt_text	string		Alternate text for the image.
href	string		A URL to link to when the image is clicked.
width	string		CSS width properties to apply to the image. (I.E. 50px)

Example

{
  "type": "image",
  "src": "../Images/logo.png"
}

List Element

The List element allows you to create ordered or unordered lists in your notification.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For list elements, this value should be list.
list_type	string	required	The type of list. Can be ordered or unordered.
elements	ListItemElement[]	required	An array of list item elements.
imgSrc	string		Allows bullets to be rendered using an image (for unordered lists).
imgHref	string		URL for the bullet image, if used.

List Item Fields

Field	Type	Required	Description
type	string	required	Should be list-item.
elements	TextContentElement[] OR ListItemElement[]	required	Content of the list item, can include nested lists.
background_color	string		Background color for the list item.

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

Meta Element

The meta element contains information describing the notification that may be used by a particular channel or provider. One important field is the title field which will be used as the title for channels that support it.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For meta elements, this value should be meta.
title	string		The title to be displayed by supported channels i.e. push, email (as subject)

Example

Set the title

{
  "type": "meta",
  "title": "Thank you for signing up!"
}

With handlebars:

{
  "type": "meta",
  "title": "Hello, {{first_name}} {{last_name}}" // comes from data (data.first_name etc)
}

Channel filtered (see control flow docs for more details):

{
  "type": "meta",
  "title": "This is an email!",
  "channels": ["email"]
},
{
  "type": "meta",
  "title": "This is a push notification!",
  "channels": ["push"]
}

Quote Element

Renders a quote block.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For quote elements, this value should be quote.
content	string	required	The text value of the quote.
align	string		Alignment of the quote. One of center, left, right, or full.
border_color	string		CSS border color property (i.e. #fff).
text_style	string		One of text, h1, h2, or subtext
locales	object		Region specific content. See locales docs for more details.

Example

{
  "type": "quote",
  "content": "The future belongs to those who believe in the beauty of their dreams"
}

Text Element

Represents a body of text to be rendered inside of the notification.

Fields

Field	Type	Required	Description
type	string	required	The type of element. For text elements, this value should be text.
content	string	required	The text content displayed in the notification. Either this field must be specified, or the elements field
elements	TextContentElement[]	required	An array of Text Content Elements. Either this field must be specified, or the content element field
align	string		Text alignment. One of left, center, or right
text_style	string		Allows the text to be rendered as a heading level. Can be text, h1, h2, or subtext
color	string		Specifies the color of text. Can be any valid css color value
bold	boolean		Apply bold to the text
italic	boolean		Apply italics to the text
strikethrough	boolean		Apply a strike through the text
underline	boolean		Apply an underline to the text
locales	object		Region specific content. See locales docs for more details.

Example

Basic usage:

{
  "type": "text",
  "content": "Thanks for signing up!"
}

With handlebars:

{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}" // comes from the message.data property (i.e. data.first_name)
}

With locales:

{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}",
  "locales": {
    "eu-fr": {
      "content": "Ceci est une notification que j'ai envoyée à {{first_name}}"
    }
  }
}

Text Content Elements

The following elements can be applied as sub elements to the main text element. For now, they must be a child of the text element.

String Element

Renders a simple string. Similar to default behavior of text without a newline applied at the end

Field	Type	Required	Description
type	string	required	The type of element. For string elements, this value should be string.
content	string	required	The text content displayed in the notification.
align	string		Text alignment. One of left, center, or right
text_style	string		Allows the text to be rendered as a heading level. Can be text, h1, h2, or subtext
color	string		Specifies the color of text. Can be any valid css color value
bold	boolean		Apply bold to the text
italic	boolean		Apply italics to the text
strikethrough	boolean		Apply a strike through the text
underline	boolean		Apply an underline to the text
locales	object		Region specific content. See locales docs for more details.

Link Element

Renders a link within a body of text.

Field	Type	Required	Description
type	string	required	The type of element. For link elements, this value should be link.
content	string	required	The text content displayed in the notification.
href	string		The address to link to
disable_tracking	boolean		Disable tracking for the link
align	string		Text alignment. One of left, center, or right
text_style	string		Allows the text to be rendered as a heading level. Can be text, h1, h2, or subtext
color	string		Specifies the color of text. Can be any valid css color value
bold	boolean		Apply bold to the text
italic	boolean		Apply italics to the text
strikethrough	boolean		Apply a strike through the text
underline	boolean		Apply an underline to the text
locales	object		Region specific content. See locales docs for more details.

Img Element

Renders an image inline within a body of text.

Field	Type	Required	Description
type	string	required	The type of element. For inline image elements, this value should be img.
src	string	required	The source address of the image
alt_text	string		Text to used for screen readers and displayed on mouse hover
width	string		How wide the image should render. Can be any valid css width value
href	string		An address to link to
disable_tracking	boolean		Disable tracking for the link
align	string		Text alignment. One of left, center, or right
text_style	string		Allows the text to be rendered as a heading level. Can be text, h1, h2, or subtext
color	string		Specifies the color of text. Can be any valid css color value
bold	boolean		Apply bold to the text
italic	boolean		Apply italics to the text
strikethrough	boolean		Apply a strike through the text
underline	boolean		Apply an underline to the text
locales	object		Region specific content. See locales docs for more details.

Example

Basic example:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Hey! ", "bold": true },
    { "type": "link", "content": "Check out this site.", "href": "https://www.example.com" },
    { "type": "img", "src": "https://emoji.com/cool-emoji", "width": "5px" }
  ]
}

Control Flow

All elements support additional properties for control flow:

Field	Type	Description
if	string	A condition that determines whether the element should be rendered.
loop	string	An expression that allows the element to be repeated multiple times.
ref	string	A reference identifier for the element.

These properties enable dynamic content generation and conditional rendering within your Elemental structure.

Examples

Conditional rendering:

{
  "type": "text",
  "content": "This will only appear for premium users",
  "if": "{{user.isPremium}}"
}

Looping:

{
  "type": "group",
  "loop": "{{items}}",
  "elements": [
    {
      "type": "text",
      "content": "Item: {{item.name}}"
    }
  ]
}

For more details on using these properties, see the control flow docs.