Elements - Courier

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.

Getting Started

Platform

Tools

​Elemental Sugar

​Fields

​Example

​Action Element

​Fields

​Example

​Channel Element

​Fields

​Example

​Comment Element

​Fields

​Example

​Group Element

​Fields

​Example

​HTML Element

​Fields

​Example

​Image Element

​Fields

​Example

​List Element

​Fields

​List Item Fields

​Example

​Meta Element

​Fields

​Example

​Quote Element

​Fields

​Example

​Text Element

​Fields

​Example

​Text Content Elements

​String Element

​Link Element

​Img Element

​Example

​Control Flow

​Examples

Elemental Sugar

Fields

Example

Action Element

Fields

Example

Channel Element

Fields

Example

Comment Element

Fields

Example

Group Element

Fields

Example

HTML Element

Fields

Example

Image Element

Fields

Example

List Element

Fields

List Item Fields

Example

Meta Element

Fields

Example

Quote Element

Fields

Example

Text Element

Fields

Example

Text Content Elements

String Element

Link Element

Img Element

Example

Control Flow

Examples