Elements

• Elemental Sugar
• Action Element
• Channel Element
• Divider Element
• Group Element
• Image Element
• Meta Element
• Quote Element
• Text Element
• Text Content 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:

// 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

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. 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.

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

Field	Type	Required	Description
type	"string"	required	The type of element. For action 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	"link"	required	The type of element. For action 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	"link"	required	The type of element. For action elements, this value should be "link".
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.

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