Elemental

You compose a notification from a list of elements. Courier renders each one for email, push, SMS, inbox, and direct message. A document has two top-level fields, and a send passes it as message.content:

{
  "message": {
    "to": { "email": "sarah@acme-corp.com" },
    "content": {
      "version": "2022-01-01",
      "elements": [
        // CourierElement[]
      ]
    }
  }
}

string

required

The Elemental format version. The only supported value is "2022-01-01".

CourierElement[]

required

The elements that make up the notification. Every type is documented below.

Two ways to write content ElementalContentSugar is a shorthand for simple notifications. Pass title and body instead of a full element tree, and omit version and elements. Courier converts it to full Elemental internally: title becomes a meta element, body becomes a text element.

const { requestId } = await client.send.message({
  message: {
    to: { email: "sarah@acme-corp.com" },
    content: {
      title: "Welcome!",
      body: "Thanks for signing up, {{name}}",
    },
    data: { name: "Sarah Bennett" },
  },
});

response = client.send.message(
    message={
        "to": {"email": "sarah@acme-corp.com"},
        "content": {
            "title": "Welcome!",
            "body": "Thanks for signing up, {{name}}",
        },
        "data": {"name": "Sarah Bennett"},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com" },
      "content": {
        "title": "Welcome!",
        "body": "Thanks for signing up, {{name}}"
      },
      "data": { "name": "Sarah Bennett" }
    }
  }'

response = courier.send_.message(
  message: {
    to: { email: "sarah@acme-corp.com" },
    content: {
      title: "Welcome!",
      body: "Thanks for signing up, {{name}}"
    },
    data: { name: "Sarah Bennett" }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Welcome!",
				Body:  "Thanks for signing up, {{name}}",
			},
		},
		Data: map[string]any{"name": "Sarah Bennett"},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .content(JsonValue.from(java.util.Map.of(
            "title", "Welcome!",
            "body", "Thanks for signing up, {{name}}")))
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com'],
    'content' => [
      'title' => 'Welcome!',
      'body' => 'Thanks for signing up, {{name}}',
    ],
    'data' => ['name' => 'Sarah Bennett'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = new ElementalContentSugar()
        {
            Title = "Welcome!",
            Body = "Thanks for signing up, {{name}}",
        },
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") }
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"title": "Welcome!", "body": "Thanks for signing up, {{name}}"}' \
  --message.data '{"name": "Sarah Bennett"}'

With Courier MCP, send an email to sarah@acme-corp.com with the title Welcome and a short thank-you body.

Use the sugar format for a title and body with no conditionals, loops, or layout. Use full Elemental for everything else: multi-channel customization, columns and groups, if/loop/ref, locales, and styling. Element nesting Elemental is a tree. The root elements array holds elements, and the container types hold their own elements arrays:

group: conditions and loops
channel: channel-specific content
columns: holds column elements
list: holds list-item elements

Nesting makes conditional groups, per-channel branches, and multi-column layouts possible.

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        { "type": "meta", "title": "Order Confirmation" },
        {
          "type": "group",
          "if": "data.items.length > 0",
          "elements": [
            {
              "type": "columns",
              "elements": [
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [{ "type": "image", "src": "{{item.image}}" }]
                },
                {
                  "type": "column",
                  "width": "50%",
                  "elements": [{ "type": "text", "content": "{{item.name}}" }]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Common properties Every element has a required type string. Each section below gives its value, for example "text" for the text element. Most elements also accept these shared properties:

channels: an array of channel names. The element renders only for the listed channels.
if: a condition that controls whether the element renders. Accepts a string expression or a .
loop: an expression that repeats the element for each item in an array.
ref: a reference identifier for the element.

below covers all four. Many elements also accept a locales object for multi-language content, covered in . Where a property is central to an element, such as if and loop on group and list, it is listed in that element’s fields below. Text fields support variables. They resolve against message.data, for example data.first_name.

The elements

Element	Use it to
	Format copy: bold, italic, links, alignment, colour.
	Add a button or a link.
	Wrap content for one channel, and override its routing.
	Set the subject line and other metadata.
	Place an image, sized, aligned, optionally a link.
	Draw a horizontal rule.
	Nest elements so one control-flow rule covers them all.
	Lay elements side by side.
	Render repeating items from your data.
	Call out a passage.
	Leave an internal remark that never renders.
	Embed raw HTML for email.
	Generate content programmatically.

Every element also takes if, loop, ref, and channels. Those four are documented once, in .

Sending a document and storing one differ

A send takes the document above as message.content and renders it for every channel it routes to. Storing the same document on a Template needs its top-level elements wrapped in a channel element. A send accepts a bare element list. The write API does not, and its rejection names a schema path rather than the rule you broke. covers the round trip.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

The elements

Sending a document and storing one differ

​The elements

​Sending a document and storing one differ

The elements

Sending a document and storing one differ