Elemental control flow

Elemental has four control flow properties:

if - Conditionally render elements based on data or conditions
loop - Repeat elements for each item in an array
ref - Reference elements to check their visibility or properties
channels - Show elements only on specific channels

All four are optional, available on every element, and can be combined on the same element.

Control flow properties are evaluated at render time using Handlebars expressions. You can read message.data, message.to.data, and other message context.

If

The if property renders an element only when a Handlebars expression is truthy. Otherwise the element is skipped. When to use:

Show different content based on user type, subscription status, or feature flags
Display elements only when certain data exists
Create personalized experiences based on user context
Hide elements that aren’t relevant to the current recipient

Applies to: All Elemental elements Basic Example

{
  "type": "text",
  "content": "Welcome, premium member!",
  "if": "data.user_tier === 'premium'"
}

const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Welcome, premium member!",
          if: "data.user_tier === 'premium'",
        },
      ],
    },
  },
});

response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Welcome, premium member!",
            "if": "data.user_tier === 'premium'",
          },
        ],
      },
    },
)

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": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "Welcome, premium member!",
              "if": "data.user_tier === '\''premium'\''"
            }
          ]
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Welcome, premium member!",
          if: "data.user_tier === 'premium'"
        }
      ]
    }
  }
)

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Welcome, premium member!",
      "if": "data.user_tier === 'premium'"
    }
  ]
}`))

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{OfElementalContent: &content},
	},
})

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(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "Welcome, premium member!",
                    "if", "data.user_tier === 'premium'")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Welcome, premium member!',
          'if' => 'data.user_tier === \'premium\'',
        ],
      ],
    ],
  ],
);

// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Welcome, premium member!",
                  "if": "data.user_tier === 'premium'"
                }
              ]
            }
            """)),
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Welcome, premium member!", "if": "data.user_tier === '\''premium'\''"}]}'

With Courier MCP, send an email to sarah@acme-corp.com and show the discount line only for premium users.

Realistic Examples Conditional welcome message based on user type:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Welcome back, {{first_name}}!",
      "if": "data.is_returning_user"
    },
    {
      "type": "text",
      "content": "Welcome to {{company_name}}, {{first_name}}!",
      "if": "!data.is_returning_user"
    },
    {
      "type": "action",
      "content": "Upgrade to Premium",
      "href": "https://example.com/upgrade",
      "if": "data.user_tier !== 'premium'"
    }
  ]
}

Show elements only when data exists:

{
  "type": "group",
  "if": "data.items && data.items.length > 0",
  "elements": [
    {
      "type": "text",
      "content": "Your order contains {{data.items.length}} item(s)"
    }
  ]
}

Structured conditions The if field also accepts a structured condition array: one or more condition groups evaluated at render time. The element renders if any group matches, so groups are OR’d together. Within a group, conditions combine using the group’s logical_operator. Supported property namespaces (dot-paths only):

Namespace	Description	Example
`data.*`	Values from the send `data` payload	`data.order_total`
`profile.*`	Recipient profile fields	`profile.plan`
`refs.*`	Visibility of another element by its `ref`	`refs.promo_banner.visible`

Supported operators:

Operator	Type	`value` required
`equals`, `not_equals`	binary	yes
`greater_than`, `less_than`, `greater_than_or_equals`, `less_than_or_equals`	binary	yes
`contains`, `not_contains`	binary	yes
`is_empty`, `is_not_empty`	unary	no

Design Studio labels these operators in prose, and three do not match their JSON key. The editor builds the same object either way. This is the mapping:

Editor reads	JSON key
does not equal	`not_equals`
is at least	`greater_than_or_equals`
is at most	`less_than_or_equals`

The other seven read as their key: equals, is greater than, is less than, contains, does not contain, is empty, is not empty. There is no empty structured condition. Delete a group’s last condition and the group goes with it. Delete the last group and the if field is removed rather than left as [], so an empty array is not the way to express “no conditions” and an element carrying one is malformed. Single group (all conditions AND’d):

{
  "type": "text",
  "content": "You qualify for the enterprise plan.",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [
        { "property": "data.account_type", "operator": "equals", "value": "enterprise" },
        { "property": "profile.email_verified", "operator": "equals", "value": "true" }
      ]
    }
  ]
}

Multiple groups (OR between groups):

{
  "type": "text",
  "content": "Upgrade available!",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.plan", "operator": "equals", "value": "free" }]
    },
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.plan", "operator": "equals", "value": "starter" }]
    }
  ]
}

Unary operator (no value needed):

{
  "type": "text",
  "content": "No promo code applied.",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "data.promo_code", "operator": "is_empty" }]
    }
  ]
}

Using refs to check element visibility:

{
  "type": "text",
  "content": "Here is what you unlocked:",
  "if": [
    {
      "logical_operator": "and",
      "conditions": [{ "property": "refs.promo_block.visible", "operator": "equals", "value": "true" }]
    }
  ]
}

String if and structured if are mutually exclusive on the same element. Use one or the other. String expressions remain fully supported.

Ref

The ref property names an element so other elements can reference it. A referenced element exposes its properties plus visible, which says whether it rendered. When to use:

Check if another element was rendered before showing related content
Create dependencies between elements
Build complex conditional logic based on element visibility
Access element properties from other elements

Applies to: All Elemental elements Note: An element can only reference elements defined earlier in the elements array. Basic Example

{
  "type": "text",
  "content": "Hello, {{first_name}}",
  "ref": "greeting"
},
{
  "type": "text",
  "content": "This shows if greeting is visible",
  "if": "refs.greeting.visible"
}

const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello, {{first_name}}",
          ref: "greeting",
        },
        {
          type: "text",
          content: "This shows if greeting is visible",
          if: "refs.greeting.visible",
        },
      ],
    },
  },
});

response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "Hello, {{first_name}}",
            "ref": "greeting",
          },
          {
            "type": "text",
            "content": "This shows if greeting is visible",
            "if": "refs.greeting.visible",
          },
        ],
      },
    },
)

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": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "Hello, {{first_name}}",
              "ref": "greeting"
            },
            {
              "type": "text",
              "content": "This shows if greeting is visible",
              "if": "refs.greeting.visible"
            }
          ]
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "Hello, {{first_name}}",
          ref: "greeting"
        },
        {
          type: "text",
          content: "This shows if greeting is visible",
          if: "refs.greeting.visible"
        }
      ]
    }
  }
)

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Hello, {{first_name}}",
      "ref": "greeting"
    },
    {
      "type": "text",
      "content": "This shows if greeting is visible",
      "if": "refs.greeting.visible"
    }
  ]
}`))

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{OfElementalContent: &content},
	},
})

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(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "Hello, {{first_name}}",
                    "ref", "greeting"),
                  java.util.Map.of(
                    "type", "text",
                    "content", "This shows if greeting is visible",
                    "if", "refs.greeting.visible")))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'Hello, {{first_name}}',
          'ref' => 'greeting',
        ],
        [
          'type' => 'text',
          'content' => 'This shows if greeting is visible',
          'if' => 'refs.greeting.visible',
        ],
      ],
    ],
  ],
);

// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "Hello, {{first_name}}",
                  "ref": "greeting"
                },
                {
                  "type": "text",
                  "content": "This shows if greeting is visible",
                  "if": "refs.greeting.visible"
                }
              ]
            }
            """)),
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "Hello, {{first_name}}", "ref": "greeting"}, {"type": "text", "content": "This shows if greeting is visible", "if": "refs.greeting.visible"}]}'

With Courier MCP, send an email to sarah@acme-corp.com that reuses an earlier element by reference.

Realistic Example Show follow-up content only if initial element is visible:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Special offer for premium members!",
      "ref": "premium_offer",
      "if": "data.user_tier === 'premium'"
    },
    {
      "type": "action",
      "content": "Claim Offer",
      "href": "https://example.com/claim",
      "if": "refs.premium_offer.visible"
    }
  ]
}

Loop

The loop property renders an element multiple times, once for each item in an iterable data source (typically an array). When to use:

Display lists of products, orders, notifications, or other array data
Create dynamic content that adapts to variable-length data
Build repeating patterns like product cards or notification items
Iterate over nested data structures

Applies to: All Elemental elements Loop variables:

$.item - The current item in the iteration
$.index - The zero-based index of the current iteration

Basic Example

{
  "type": "text",
  "content": "* {{$.item.name}} - {{$.item.price}}",
  "loop": "data.products"
}

const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "* {{$.item.name}} - {{$.item.price}}",
          loop: "data.products",
        },
      ],
    },
    data: {
      products: [
        { name: "Notebook", price: 12.5 },
        { name: "Pen", price: 3 },
      ],
    },
  },
});

response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "* {{$.item.name}} - {{$.item.price}}",
            "loop": "data.products",
          },
        ],
      },
      "data": {
        "products": [
          {"name": "Notebook", "price": 12.5},
          {"name": "Pen", "price": 3},
        ],
      },
    },
)

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": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "* {{$.item.name}} - {{$.item.price}}",
              "loop": "data.products"
            }
          ]
        },
        "data": {
          "products": [
            { "name": "Notebook", "price": 12.5 },
            { "name": "Pen", "price": 3 }
          ]
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "* {{$.item.name}} - {{$.item.price}}",
          loop: "data.products"
        }
      ]
    },
    data: {
      products: [
        { name: "Notebook", price: 12.5 },
        { name: "Pen", price: 3 }
      ]
    }
  }
)

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "* {{$.item.name}} - {{$.item.price}}",
      "loop": "data.products"
    }
  ]
}`))

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{OfElementalContent: &content},
		Data: map[string]any{
			"products": []any{
				map[string]any{"name": "Notebook", "price": 12.5},
				map[string]any{"name": "Pen", "price": 3},
			},
		},
	},
})

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(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "* {{$.item.name}} - {{$.item.price}}",
                    "loop", "data.products")))))
        .data(JsonValue.from(java.util.Map.of(
                "products", java.util.List.of(
                  java.util.Map.of("name", "Notebook", "price", 12.5),
                  java.util.Map.of("name", "Pen", "price", 3)))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => '* {{$.item.name}} - {{$.item.price}}',
          'loop' => 'data.products',
        ],
      ],
    ],
    'data' => [
      'products' => [
        ['name' => 'Notebook', 'price' => 12.5],
        ['name' => 'Pen', 'price' => 3],
      ],
    ],
  ],
);

// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "* {{$.item.name}} - {{$.item.price}}",
                  "loop": "data.products"
                }
              ]
            }
            """)),
        Data = new Dictionary<string, JsonElement>()
        {
            { "products", JsonSerializer.SerializeToElement(new[]
                {
                    new { name = "Notebook", price = 12.5 },
                    new { name = "Pen", price = 3 },
                })
            },
        },
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "* {{$.item.name}} - {{$.item.price}}", "loop": "data.products"}]}' \
  --message.data '{"products": [{"name": "Notebook", "price": 12.5}, {"name": "Pen", "price": 3}]}'

With Courier MCP, send an email to sarah@acme-corp.com listing the two products in data.products, one line per item.

Realistic Examples Product list with nested data:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "group",
      "loop": "data.products",
      "elements": [
        {
          "type": "text",
          "content": "{{$.item.name}}",
          "text_style": "h2"
        },
        {
          "type": "text",
          "content": "Price: {{$.item.price}}"
        },
        {
          "type": "image",
          "src": "{{$.item.image_url}}",
          "alt_text": "{{$.item.name}}"
        },
        {
          "type": "action",
          "content": "View Details",
          "href": "https://example.com/products/{{$.item.id}}"
        },
        {
          "type": "divider"
        }
      ]
    }
  ]
}

Using $.index for item numbering:

To show a 1-based item number, pass $.index to the add :

Item {{add $.index 1}}: {{$.item.name}}

This outputs “Item 1”, “Item 2”, and so on, instead of starting at zero.

{
  "type": "text",
  "content": "Item {{add $.index 1}}: {{$.item.name}} - {{$.item.price}}",
  "loop": "data.products"
}

Channels

The channels property renders an element only on the channels you list. Use it to show different content on email, SMS, push, and other channels. When to use:

Show detailed content in email, concise content in SMS
Display channel-specific formatting or elements
Customize content per channel while maintaining a single template
Hide elements that don’t work well on certain channels

Applies to: All Elemental elements Valid channels: email, push, direct_message, sms, or provider-specific channels like slack, discord, etc.

For a fully different content structure per channel, use .

Basic Example

{
  "type": "text",
  "content": "This only appears in email and push",
  "channels": ["email", "push"]
}

const { requestId } = await client.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "This only appears in email and push",
          channels: [
            "email",
            "push",
          ],
        },
      ],
    },
  },
});

response = client.send.message(
    message={
      "to": {
        "email": "sarah@acme-corp.com",
      },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "text",
            "content": "This only appears in email and push",
            "channels": [
              "email",
              "push",
            ],
          },
        ],
      },
    },
)

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": {
          "version": "2022-01-01",
          "elements": [
            {
              "type": "text",
              "content": "This only appears in email and push",
              "channels": [
                "email",
                "push"
              ]
            }
          ]
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    content: {
      version: "2022-01-01",
      elements: [
        {
          type: "text",
          content: "This only appears in email and push",
          channels: [
            "email",
            "push"
          ]
        }
      ]
    }
  }
)

// Elemental nodes carry no typed content fields, so pass the document as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "This only appears in email and push",
      "channels": [
        "email",
        "push"
      ]
    }
  ]
}`))

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{OfElementalContent: &content},
	},
})

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(
                "version", "2022-01-01",
                "elements", java.util.List.of(
                  java.util.Map.of(
                    "type", "text",
                    "content", "This only appears in email and push",
                    "channels", java.util.List.of(
                      "email",
                      "push"))))))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'text',
          'content' => 'This only appears in email and push',
          'channels' => [
            'email',
            'push',
          ],
        ],
      ],
    ],
  ],
);

// Elemental nodes expose no typed content fields, so build the document from raw JSON.
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Content = ElementalContent.FromRawUnchecked(
            JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
            {
              "version": "2022-01-01",
              "elements": [
                {
                  "type": "text",
                  "content": "This only appears in email and push",
                  "channels": [
                    "email",
                    "push"
                  ]
                }
              ]
            }
            """)),
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.content '{"version": "2022-01-01", "elements": [{"type": "text", "content": "This only appears in email and push", "channels": ["email", "push"]}]}'

With Courier MCP, send an email and a push to sarah@acme-corp.com, showing the footer on email only.

Realistic Examples Channel-specific content:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "text",
      "content": "Your order #{{order_number}} has shipped! Track it here: {{tracking_url}}",
      "channels": ["email"]
    },
    {
      "type": "text",
      "content": "Order {{order_number}} shipped. Track: {{tracking_url}}",
      "channels": ["sms"]
    },
    {
      "type": "text",
      "content": "Your order has shipped!",
      "channels": ["push"]
    }
  ]
}

Hide complex elements on SMS:

{
  "type": "columns",
  "channels": ["email"],
  "elements": [
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "image",
          "src": "{{product_image}}"
        }
      ]
    },
    {
      "type": "column",
      "width": "50%",
      "elements": [
        {
          "type": "text",
          "content": "{{product_name}}"
        }
      ]
    }
  ]
}

Combining Control Flow Properties You can combine multiple control flow properties on the same element:

{
  "type": "text",
  "content": "Premium feature available!",
  "if": "data.user_tier === 'premium'",
  "channels": ["email", "push"],
  "ref": "premium_notice"
}

Evaluation order:

channels - Element must match current channel
if - Condition must evaluate to truthy
loop - Element is repeated for each item (if present)
ref - Element is registered for reference (if present)

Best practices

Use if for conditional content: Show/hide elements based on data or user context
Use loop with group: Wrap looped elements in a group for better organization
Reference order matters: Elements must be defined before they’re referenced
Test with real data: Control flow expressions are evaluated at render time, so test with realistic data structures
Combine with locales: Use control flow with for fully dynamic, multi-language notifications
Channel considerations: some elements (like columns) may not render well on all channels

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Elemental control flow

If

Ref

Loop

Channels

Best practices

​If

​Ref

​Loop

​Channels

​Best practices

If

Ref

Loop

Channels

Best practices