Elements
Elemental Sugar
Syntatic 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. |
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
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. |
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
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 . |
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
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 . |
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
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. |
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
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) |
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
Field | Type | Required | Description |
---|---|---|---|
type | string | required | The type of element. For image elements, this value should be "meta" . |
title | string | The 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
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. |
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
Field | Type | Required | Description |
---|---|---|---|
type | string | required | The type of element. For action elements, this value should be "text" . |
content | string | required | The text content displayed in the notification. |
locales | object | Region 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}}"
}
}
}