Channel

Overview

The channel element allows you to customize notification content based on which channel the notification is sent through. For example, you can display a detailed message in email and a more concise message in push notifications. When to use:

Provide channel-specific content (different content for email vs push vs SMS)
Use raw channel data for provider-specific formats (MJML for email, Slack blocks, etc.)
Create channel-specific layouts and structures

Channel elements are only valid as top-level elements. You cannot nest channel elements. If a channel element is specified at the top level, all sibling elements must be channel elements.

Alternative: Most elements support a channels property that allows you to selectively display individual elements on a per-channel basis. See the Control Flow documentation for details.

Basic Example

{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "meta",
      "title": "My Subject"
    },
    {
      "type": "text",
      "content": "My email body"
    }
  ]
}

import Courier from "@trycourier/courier";

const courier = new Courier({
  apiKey: process.env.COURIER_API_KEY,
});

await courier.send.message({
  message: {
    to: { email: "user@example.com" },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "channel",
          channel: "email",
          elements: [
            {
              type: "meta",
              title: "Welcome Email",
            },
            {
              type: "text",
              content: "Thanks for signing up! Check your email for details.",
            },
          ],
        },
        {
          type: "channel",
          channel: "default",
          elements: [
            {
              type: "meta",
              title: "Welcome",
            },
            {
              type: "text",
              content: "Thanks for signing up!",
            },
          ],
        },
      ],
    },
  },
});

import os
from courier import Courier

client = Courier(api_key=os.environ["COURIER_API_KEY"])

client.send.message(
    message={
        "to": {"email": "user@example.com"},
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [
                        {"type": "meta", "title": "Welcome Email"},
                        {
                            "type": "text",
                            "content": "Thanks for signing up! Check your email for details.",
                        },
                    ],
                },
                {
                    "type": "channel",
                    "channel": "default",
                    "elements": [
                        {"type": "meta", "title": "Welcome"},
                        {"type": "text", "content": "Thanks for signing up!"},
                    ],
                },
            ],
        },
    }
)

Fields

type

string

required

The type of element. For channel elements, this value must be "channel".

channel

string

required

The channel the contents of this element should be applied to. Can be:

Standard channels: "email", "push", "direct_message", "sms"
Provider names: "slack", "discord", "teams", etc.
"default" - applies to all channels not explicitly specified

elements

CourierElement[]

An array of Elemental elements to apply to the channel. If raw has not been specified, elements is required.

raw

object

Raw data to apply to the channel. This allows you to provide channel-specific formats like MJML for email, Slack blocks, or webhook payloads. If elements has not been specified, raw is required.

font_family

string

The CSS font-family stack to apply to the rendered email. Only valid when channel is "email". Use the exact fontFamily value from the font catalog. Google Fonts are loaded automatically. Defaults to Helvetica, Arial, sans-serif if omitted.

{
  "type": "channel",
  "channel": "email",
  "font_family": "Roboto, Arial, sans-serif",
  "elements": [...]
}

Examples & Variants

Using Elements

Provide different Elemental content per channel:

{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "meta",
      "title": "Order Confirmation"
    },
    {
      "type": "text",
      "content": "Your order #{{order_id}} has been confirmed. We'll send you tracking information once your order ships."
    },
    {
      "type": "action",
      "content": "View Order",
      "href": "https://app.example.com/orders/{{order_id}}"
    }
  ]
},
{
  "type": "channel",
  "channel": "push",
  "elements": [
    {
      "type": "meta",
      "title": "Order Confirmed"
    },
    {
      "type": "text",
      "content": "Order #{{order_id}} confirmed"
    }
  ]
}

Using Raw Data

Use raw channel data for provider-specific formats:

Email with MJML

{
  "type": "channel",
  "channel": "email",
  "raw": {
    "subject": "Order Confirmation",
    "html": "<mjml><mj-body><mj-section><mj-column><mj-text>Your order has been confirmed!</mj-text></mj-column></mj-section></mj-body></mjml>",
    "text": "Your order has been confirmed!",
    "transformers": ["handlebars", "mjml"]
  }
}

Slack

{
  "type": "channel",
  "channel": "slack",
  "raw": {
    "text": "Hello World!",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "Your order has been confirmed!"
        }
      }
    ]
  }
}

Webhook

{
  "type": "channel",
  "channel": "webhook",
  "raw": {
    "payload": {
      "body": {
        "event": "order.confirmed",
        "order_id": "{{order_id}}",
        "timestamp": "{{timestamp}}"
      }
    }
  }
}

Default Channel

Use "default" to provide content for all channels not explicitly specified:

{
  "type": "channel",
  "channel": "email",
  "elements": [
    {
      "type": "text",
      "content": "Detailed email content here"
    }
  ]
},
{
  "type": "channel",
  "channel": "default",
  "elements": [
    {
      "type": "text",
      "content": "Content for push, SMS, and other channels"
    }
  ]
}

Channel-Specific Considerations

Email

Supports full Elemental elements or raw HTML/MJML
Can use raw.subject for email subject line
Supports transformers array for templating engines

Push

Typically uses meta.title for notification title
Content should be concise due to character limits
Supports action buttons via action elements

SMS

Very limited character count
Best for short, essential messages
No rich formatting support

Direct Message (Slack, Discord, Teams, etc.)

Provider-specific formats via raw property
Can use provider-specific block structures
Supports rich interactive elements per provider

Meta Element - For channel-specific titles and subjects
Text Element - For channel-specific body content
Action Element - For channel-specific call-to-action buttons
Control Flow - For using channels property on individual elements

Platform

Developer Tools

Help

Overview

Basic Example

Fields

Examples & Variants

Using Elements

Using Raw Data

Email with MJML

Slack

Webhook

Default Channel

Channel-Specific Considerations

Email

Push

SMS

Direct Message (Slack, Discord, Teams, etc.)

​Overview

​Basic Example

​Fields

​Examples & Variants

​Using Elements

​Using Raw Data

​Email with MJML

​Slack

​Webhook

​Default Channel

​Channel-Specific Considerations

​Email

​Push

​SMS

​Direct Message (Slack, Discord, Teams, etc.)

​Related Elements

Overview

Basic Example

Fields

Examples & Variants

Using Elements

Using Raw Data

Email with MJML

Slack

Webhook

Default Channel

Channel-Specific Considerations

Email

Push

SMS

Direct Message (Slack, Discord, Teams, etc.)

Related Elements