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:

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

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

{
"type": "channel", // all other channels
"elements": [
{
"type": "meta",
"title": "My Title"
},
{
"type": "text",
"content": "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": "https://www.courier.com/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".
contentstringrequiredThe text content displayed in the notification.
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}}"
}
}
}