Skip to main content

Elements

Elemental Sugar

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

Fields

FieldTypeRequiredDescription
titlestringThe title to be displayed by supported channels i.e. push, email (as subject)
bodystringrequiredThe text content displayed in the notification.

Examples

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

Feel free to use Elemental Sugar 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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For action elements, this value should be "action".
contentstringrequiredThe text content of the action shown to the user.
hrefstringrequiredThe target URL of the action.
action_idstringA unique id used to identify the action when it is executed.
alignstringThe alignment of the action button. One of "center", "left", "right", or "full". Defaults to "center".
background_colorstringThe background color of the action button.
stylestringCan be "button" or "link". Defaults to "button".
localesobjectRegion specific content. See locales docs for more details.

Examples

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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For channel elements, this value should be "channel".
channelstringrequiredThe channel the contents of this element should be applied to. Can be email, push, direct_message, sms or a provider such as slack
elementsCourierElement[]An array of elements to apply to the channel. If raw has not been specified, elements is required.
rawobjectRaw data to apply to the channel. See example. If elements has not been specified, raw is required.

Examples

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

Divider Element

Renders a dividing line between elements.

Fields

FieldTypeRequiredDescription
typestringrequiredThe type of element. For divider elements, this value should be "divider".
colorstringThe CSS color to render the line with. I.E. #fff.

Examples

{
"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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For group elements, this value should be "group".
elementsCourierElement[]requiredSub elements to render.

Examples

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

Image Element

Used to embed an image into the notification.

Fields

FieldTypeRequiredDescription
typestringrequiredThe type of element. For image elements, this value should be "image".
srcstringrequiredThe source of the image.
alignstringThe alignment of the image. One of "center", "left", "right", or "full".
alt_textstringAlternate text for the image.
hrefstringA URL to link to when the image is clicked.
widthstringCSS width properties to apply to the image. (I.E. 50px)

Examples

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

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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For image elements, this value should be "meta".
titlestringThe title to be displayed by supported channels i.e. push, email (as subject)

Examples

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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For quote elements, this value should be "quote".
contentstringrequiredThe text value of the quote.
alignstringAlignment of the quote. One of "center", "left", "right", or "full".
border_colorstringCSS border color property (i.e. #fff).
text_stylestringOne of "text", "h1", "h2", or "subtext"
localesobjectRegion specific content. See locales docs for more details.

Examples

{
"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

FieldTypeRequiredDescription
typestringrequiredThe type of element. For action elements, this value should be "text".
contentstringrequired*The text content displayed in the notification. Either this field must be specified, or the elements field
elementsTextContentElement[]required*An array of Text Content Elements. Either this field must be specified, or the content element field
alignstringText alignment. One of "left", "center", or "right"
text_stylestringAllows the text to be rendered as a heading level. Can be "text", "h1", "h2", or "subtext"
colorstringSpecifies the color of text. Can be any valid css color value
boldbooleanApply bold to the text
italicbooleanApply italics to the text
strikethroughbooleanApply a strike through the text
underlinebooleanApply an underline to the text
localesobjectRegion specific content. See locales docs for more details.

Examples

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

FieldTypeRequiredDescription
type"string"requiredThe type of element. For action elements, this value should be "string".
contentstringrequiredThe text content displayed in the notification.
alignstringText alignment. One of "left", "center", or "right"
text_stylestringAllows the text to be rendered as a heading level. Can be "text", "h1", "h2", or "subtext"
colorstringSpecifies the color of text. Can be any valid css color value
boldbooleanApply bold to the text
italicbooleanApply italics to the text
strikethroughbooleanApply a strike through the text
underlinebooleanApply an underline to the text
localesobjectRegion specific content. See locales docs for more details.

Renders a link within a body of text.

FieldTypeRequiredDescription
type"link"requiredThe type of element. For action elements, this value should be "link".
contentstringrequiredThe text content displayed in the notification.
hrefstringThe address to link to
disable_trackingbooleanDisable tracking for the link
alignstringText alignment. One of "left", "center", or "right"
text_stylestringAllows the text to be rendered as a heading level. Can be "text", "h1", "h2", or "subtext"
colorstringSpecifies the color of text. Can be any valid css color value
boldbooleanApply bold to the text
italicbooleanApply italics to the text
strikethroughbooleanApply a strike through the text
underlinebooleanApply an underline to the text
localesobjectRegion specific content. See locales docs for more details.

Img Element

Renders an image inline within a body of text.

FieldTypeRequiredDescription
type"link"requiredThe type of element. For action elements, this value should be "link".
srcstringrequiredThe source address of the image
alt_textstringText to used for screen readers and displayed on mouse hover
widthstringHow wide the image should render. Can be any valid css width value
hrefstringAn address to link to
disable_trackingbooleanDisable tracking for the link
alignstringText alignment. One of "left", "center", or "right"
text_stylestringAllows the text to be rendered as a heading level. Can be "text", "h1", "h2", or "subtext"
colorstringSpecifies the color of text. Can be any valid css color value
boldbooleanApply bold to the text
italicbooleanApply italics to the text
strikethroughbooleanApply a strike through the text
underlinebooleanApply an underline to the text
localesobjectRegion specific content. See locales docs for more details.

Examples

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