Text

Overview

The text element renders a block of text, and it’s the most commonly used Elemental element. Give it content one of two ways:

content: a plain string, with Handlebars variables for dynamic values. Best for simple text.
elements: an array of inline pieces (string, link, img). Use it when one block needs links, inline images, or mixed formatting.

Style the whole block with text_style (for headings), align, color, bold, and the related fields below.

Basic Example

{
  "type": "text",
  "content": "Thanks for signing up!"
}

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: "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": "text", "content": "Thanks for signing up!"}
            ],
        },
    }
)

Fields

string

required

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

string

The text content displayed in the notification. Either this field or the elements field must be specified. Supports Handlebars variables for dynamic content.

TextContentElement[]

An array of Text Content Elements (string, link, img). Either this field or the content field must be specified. If both are present, elements takes precedence and content is ignored. See the Text Content Elements section below.

string

Text alignment. One of "left", "center", or "right". Defaults to "left".

string

Allows the text to be rendered as a heading level. Can be "text", "h1", "h2", or "subtext". Defaults to "text".

string

Padding around the text block, as a CSS padding value. Accepts one to four values (e.g., "18px" or "18px 25px 18px 25px").

string

Specifies the color of text. Can be any valid CSS color value (e.g., "#007bff", "rgb(0, 123, 255)").

boolean

Apply bold formatting to the text.

boolean

Apply italic formatting to the text.

boolean

Apply a strikethrough to the text.

boolean

Apply an underline to the text.

string

Font size for this text block, as a CSS px value (e.g., "16px"). Email only. Overrides the size of the text_style preset, so it resizes headings as well as body text, and it takes precedence over the document-level font_size on the email channel element.

string

Line height for this text block, as a CSS px value or a unitless multiplier (e.g., "24px" or "1.5"). Email only. Takes precedence over the document-level line_height on the email channel element.

object

Region-specific content for localization. Locale entries for text nodes can include content (a string), elements (a structured array of inline nodes), or both. When both are provided, elements takes precedence. See the Locales documentation for more details.

string[]

An array of channel names. The text will only be rendered for the specified channels. See Control Flow documentation for details.

Examples & Variants

Text with Handlebars

Dynamic text with variables:

{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}"
}

Variables come from message.data (e.g., data.first_name).

Empty Text as a Spacer

An empty or whitespace content with padding adds vertical space between blocks.

{
  "type": "text",
  "content": " ",
  "padding": "0 0 24px"
}

Styled Text

Text with formatting:

{
  "type": "text",
  "content": "Important Notice",
  "text_style": "h2",
  "bold": true,
  "color": "#007bff",
  "align": "center"
}

Custom Size and Line Height

Set typography on a single block when it should differ from the rest of the email:

{
  "type": "text",
  "content": "This offer expires in 24 hours.",
  "font_size": "13px",
  "line_height": "1.4",
  "color": "#6b7280"
}

Both fields are email-only. To set a baseline for every block at once, use font_size and line_height on the email channel element instead, and reserve the block-level fields for the exceptions.

Localized Text

Text with translations using the content string format:

{
  "type": "text",
  "content": "This is a notification I sent to {{first_name}}",
  "locales": {
    "es": {
      "content": "Esta es una notificación que envié a {{first_name}}"
    },
    "fr": {
      "content": "Ceci est une notification que j'ai envoyée à {{first_name}}"
    }
  }
}

Localized Text with Structured Elements

When your text node uses the elements array, provide locale translations as elements arrays to preserve inline formatting across languages:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Your order " },
    { "type": "string", "content": "#{{order.id}}", "bold": true },
    { "type": "string", "content": " has been confirmed." }
  ],
  "locales": {
    "fr": {
      "elements": [
        { "type": "string", "content": "Votre commande " },
        { "type": "string", "content": "#{{order.id}}", "bold": true },
        { "type": "string", "content": " a été confirmée." }
      ]
    }
  }
}

When Both `content` and `elements` Are Present

If a text node includes both content and elements, only elements is used, and content is ignored. Choose one format per node to keep your templates clear. The same applies to locale entries.

If a text node uses elements but a locale only provides content, Courier wraps the content string into a single-element array for backward compatibility. This preserves rendering but loses any inline formatting the original elements may have had. For full formatting fidelity, provide elements in your locale translations. See the Locales documentation for the full resolution table.

Heading Styles

Use text as headings:

{
  "type": "text",
  "content": "Welcome to Our Platform",
  "text_style": "h1"
},
{
  "type": "text",
  "content": "Get started in minutes",
  "text_style": "subtext"
}

Each text_style carries a preset size. Add font_size when one heading needs a size the preset doesn’t give you — it overrides the preset for that block only, and leaves every other heading alone:

{
  "type": "text",
  "content": "Welcome to Our Platform",
  "text_style": "h1",
  "font_size": "32px"
}

Text Content Elements

The text element can contain an array of text content elements instead of (or in addition to) the content field. These sub-elements allow you to create rich, inline text with links, images, and formatted strings.

string, link, and img elements must be children of a text element’s elements array. They cannot be used as standalone top-level elements.

string and link share the same optional formatting fields: align ("left"/"center"/"right"), text_style ("text"/"h1"/"h2"/"subtext"), color, bold, italic, strikethrough, underline, and locales. Each element’s type-specific fields are below.

String

An inline run of text. Supports the shared formatting fields above.

string

required

Must be "string".

string

required

The text to display.

Link

A clickable link within text. Supports the shared formatting fields above.

string

required

Must be "link".

string

required

The clickable text.

string

The destination URL. When provided, the link becomes clickable.

boolean

Disable click tracking. Courier tracks link clicks by default.

Img

An inline image within text.

string

required

Must be "img".

string

required

The image source. Must be a publicly accessible URL.

string

Text for screen readers, shown when the image cannot load. Important for accessibility.

string

How wide the image renders, as a CSS width (e.g., "50px", "100%").

string

A destination URL. Makes the image clickable.

boolean

Disable click tracking when href is set.

string

Alignment. One of "left", "center", or "right".

object

Region-specific overrides, including src and href.

Examples with Text Content Elements

Text with Inline Links

Combine strings and links:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Hey! " },
    { "type": "link", "content": "Check out this site.", "href": "https://www.example.com" },
    { "type": "string", "content": " It's awesome!" }
  ]
}

Text with Inline Images

Include images within text:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Check out this emoji: " },
    { "type": "img", "src": "https://emoji.com/cool-emoji", "width": "20px", "alt_text": "Cool emoji" },
    { "type": "string", "content": " Pretty cool, right?" }
  ]
}

Rich Formatted Text

Mix strings, links, and formatting:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Welcome, ", "bold": true },
    { "type": "string", "content": "{{user_name}}", "bold": true, "color": "#007bff" },
    { "type": "string", "content": "! Visit our " },
    { "type": "link", "content": "documentation", "href": "https://docs.example.com", "bold": true },
    { "type": "string", "content": " to get started." }
  ]
}

Text with Multiple Links

Multiple links in one text element:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Check out our " },
    { "type": "link", "content": "blog", "href": "https://example.com/blog" },
    { "type": "string", "content": " and " },
    { "type": "link", "content": "documentation", "href": "https://example.com/docs" },
    { "type": "string", "content": " for more information." }
  ]
}

Best Practices

Use content for simple text: When you just need plain text, use the content field
Use elements for rich formatting: Use the elements array when you need inline links, images, or complex formatting
Avoid specifying both: When both content and elements are present, elements takes precedence and content is ignored. Pick one format per node
Match locale format to root format: If your text node uses elements, provide elements in your locales to preserve formatting. A content-only locale on an elements node will work but loses inline formatting
Keep text concise: Long paragraphs can be hard to read, especially in email
Use headings appropriately: Use text_style to create proper heading hierarchy
Test formatting: Different channels may render formatting differently

Channel Support

Email: ✅ Full support with all formatting options
Push: ✅ Supported (formatting may be limited)
SMS: ⚠️ Limited support (plain text only)
Inbox: ✅ Full support with rich formatting

Action Element - For standalone buttons and links
Image Element - For standalone images
Quote Element - For quote blocks
Group Element - For grouping text with other elements
Locales - For localizing text content
Control Flow - For conditional rendering and loops

Platform

Developer Tools

Help

Overview

Basic Example

Fields

Examples & Variants

Text with Handlebars

Empty Text as a Spacer

Styled Text

Custom Size and Line Height

Localized Text

Localized Text with Structured Elements

When Both `content` and `elements` Are Present

Heading Styles

Text Content Elements

String

Link

Img

Examples with Text Content Elements

Text with Inline Links

Text with Inline Images

Rich Formatted Text

Text with Multiple Links

Best Practices

Channel Support

​Overview

​Basic Example

​Fields

​Examples & Variants

​Text with Handlebars

​Empty Text as a Spacer

​Styled Text

​Custom Size and Line Height

​Localized Text

​Localized Text with Structured Elements

​When Both content and elements Are Present

​Heading Styles

​Text Content Elements

​String

​Link

​Img

​Examples with Text Content Elements

​Text with Inline Links

​Text with Inline Images

​Rich Formatted Text

​Text with Multiple Links

​Best Practices

​Channel Support

​Related Elements

Overview

Basic Example

Fields

Examples & Variants

Text with Handlebars

Empty Text as a Spacer

Styled Text

Custom Size and Line Height

Localized Text

Localized Text with Structured Elements

When Both `content` and `elements` Are Present

Heading Styles

Text Content Elements

String

Link

Img

Examples with Text Content Elements

Text with Inline Links

Text with Inline Images

Rich Formatted Text

Text with Multiple Links

Best Practices

Channel Support

Related Elements