> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Design Studio

> Build a template in the visual editor: drag blocks onto the canvas, write per-channel content, add variables and translations, then preview and publish.

You write a notification here rather than in code, and a product manager can edit the wording after you ship it. One template holds every channel the message goes out on, each with its own content.

![Design Studio: the channel rail and blocks panel on the left, the canvas in the center, and the styles panel on the right](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/design-studio.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=51850c52555d0647e10435c5d0bc6ef2)

## Design a template

**1. Create a Template**

Open [Templates](https://app.courier.com/content/templates), select **Add template**, and choose **Design Studio v2**. Name it and create it.

> [!NOTE]
>
> This page documents **Design Studio v2**. The other editor in the console is [Classic Designer](https://www.courier.com/docs/design/templates/classic-designer.md).

**2. Pick a channel and its routing**

Select the **Email** channel tab to activate it. Open the **routing selector** in the toolbar to choose which Provider delivers it. Routing configurations are reusable across Templates, so a change applies everywhere. See [routing](https://www.courier.com/docs/send/routing.md).

**3. Add content**

Drag blocks onto the canvas: **Text** for the message, **Button** for the call to action, plus **Heading**, **Image**, **Divider**, and **Spacer**. Select a block to edit it inline. Use the settings panel for alignment, size, and color. Courier auto-saves.

![The template editor: channel rail and blocks on the left, canvas in the center, styles panel on the right](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/design-studio.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=51850c52555d0647e10435c5d0bc6ef2)

**4. Insert a variable**

Type `{{` to open the variable picker, or select the variable icon in the block toolbar. Variables are **double-braced**:

* `{{profile.name}}` for a Profile field
* `{{data.invite_url}}` for send data
* `{{tenant.name}}` and `{{tenant.properties.tier}}` for the [tenant](https://www.courier.com/docs/tenants/context.md) on the send
* `{{urls.preferences}}` and `{{urls.unsubscribe}}` for the built-in links

Every variable needs its namespace prefix. A bare `{{invite_url}}` doesn't fall back to `data`, so the editor marks it invalid. See [variables](https://www.courier.com/docs/design/templates/variables.md).

**5. Build per-channel variants**

Switch channel tabs to build variants for SMS, push, in-app, and chat. Each channel gets an editor built for its format. Courier adapts shared content to each channel's requirements.

**6. Add translations**

To send the template in more than one language, select the globe icon and pick a language. With **Translate with AI** checked, Courier translates every string, and you review each one next to the default. See [template translations](https://www.courier.com/docs/design/elemental/locales.md#translate-in-design-studio).

**7. Preview and send a test**

Select **Preview & Test**, create a test event, then fill the `data` and `profile` objects with values matching your variables:

```json theme={null}
{
  "data": { "invite_url": "https://www.acme-corp.com/invite" },
  "profile": { "email": "sarah@acme-corp.com", "name": "Sarah Bennett" }
}
```

The preview renders every channel variant with your data. A variable still showing as raw `{{...}}` means the path doesn't match your test event. **Send Test** delivers a live copy to yourself, so you catch broken links before publishing.

**8. Apply a Brand and publish**

Optionally apply a [Brand](https://www.courier.com/docs/design/brands.md) from the toolbar for a consistent logo, colors, header, and footer. Then select **Publish**. Edits stay in the draft until you publish.

Copy the Template ID from the top of the editor.

## Layout

Three areas, left to right:

1. **Channel tabs** switch between Email, SMS, Push, In-App, Slack, and MS Teams.
2. **Canvas** is where you drag blocks and edit content.
3. **Settings** holds the selected block's options.

The toolbar carries the Brand selector, routing selector, version history, the globe icon for [translations](https://www.courier.com/docs/design/elemental/locales.md#translate-in-design-studio), **Preview & Test**, and [template settings](https://www.courier.com/docs/design/templates/template-settings.md) (name, alias, subscription topic, conditions).

## Channels

Not every block works on every channel.

| Channel | Blocks | Notes |
| - | - | - |
| **Email** | All | Full HTML, images, HTML blocks, Brand header and footer, and custom [fonts](https://www.courier.com/docs/design/elemental/fonts.md) |
| **SMS** | Text only | No formatting. Variables work. Carrier character limits apply. |
| **Push** | Text only | Title and body. Length limits vary by platform. |
| **In-App** | Text only | Renders in the [Courier Inbox](https://www.courier.com/docs/in-app/overview.md). |
| **Slack** | Subset | |
| **Microsoft Teams** | Subset | |

## Available blocks

| Block | What it does | Notes |
| - | - | - |
| **Heading** | Large text for titles and section headers | Choose the heading level (H1, H2, H3). A heading is a text block with a heading level, so it also supports variables and alignment. |
| **Text** | Paragraphs of body copy | Rich formatting (bold, italic, links, lists) on email. Variables work on every channel, with plain text on SMS, push, and Inbox. |
| **Image** | Embeds an image | Set the image URL (or a variable), alt text for accessibility, an optional link, and width or alignment. |
| **Button** | Clickable call-to-action button | See [Buttons](#buttons) for label, link, and style settings. |
| **Spacer** | Adds vertical space between blocks | Adjust the height in the block settings. |
| **Divider** | Horizontal line between sections | Set color, thickness, and corner radius in the block settings. |
| **List** | Bulleted or numbered list | See [Lists](#lists) for ordered vs. unordered types and looping over a data array. |
| **Column** | Multi-column layout | See [Columns](#columns) for column count and per-cell styling. |
| **HTML** | Raw HTML for custom markup | See [HTML](#html) for inline blocks and whole-email HTML. |
| **Blockquote** | Quoted or highlighted text for testimonials and pull quotes | Not in the default sidebar yet. Add it from the slash menu or when it is enabled for your workspace. |

## Adding blocks

**1. Select a channel**

Pick a channel from the left sidebar.

**2. Drag a block onto the canvas**

Drag a block from the block sidebar to the spot you want.

**3. Reorder as needed**

Drag blocks up or down to reorder them.

![Block sidebar in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-toolbar.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=0f42bd934972e032d090696d5d9151e1)

Block Sidebar

## Block settings

Click a block and its settings open in the right panel, varying by block type. [Block settings](https://www.courier.com/docs/design/templates/blocks.md) is the reference for every setting each block exposes, with its default. Settings may include:

* **Frame**: padding and margin.
* **Border**: border style and radius.
* **Alignment**: text and content alignment.
* **Colors**: background and text colors.

![Block settings panel](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-block-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=33e2ee15ca27989548d1416b39663b6f)

Block Settings

## Copying and removing blocks

When you select a block, action icons appear:

* **Copy**: duplicate the block directly below.
* **Delete**: remove the block from the canvas.

![Copy and delete block actions](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-block-remove.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=6096682fa0009caedbe187006ef74c76)

Block Actions

## Buttons

Select a button block to open its settings:

* **Label**: text on the button. [Variables](https://www.courier.com/docs/design/templates/variables.md) work here (e.g. `View {{data.product_name}}`).
* **Link URL**: where the button goes. Variables work here too.
* **Alignment**: left, center, or right.
* **Background color**: button fill color.
* **Border radius**: corner rounding.
* **Border size**: outline thickness.
* **Padding**: space around the button.

![Button block in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-button-new.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=707b04750dd7aa5bf88dcf06466bb8de)

Button Block

## Lists

Select a List block to open its settings:

* **Type**: toggle between **Unordered** (bulleted) and **Ordered** (numbered).
* **Padding**: horizontal and vertical padding in pixels.
* **Loop on**: repeat the list for each item in a data array (see below).

![List block settings panel showing type, padding, and loop on toggle](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-list-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=6437015ed04ab696c3b2e4500f197b99)

List Settings

### Looping over data

The **Loop on** toggle repeats the list for each item in a data array you send on the [Send API](https://www.courier.com/docs/api-reference/send/send-a-message.md) call.

**1. Enable Loop on**

Select the List block and turn on **Loop on**.

**2. Set the data path**

Enter a **Data path** pointing to an array in your `data` payload (e.g. `data.order_items`). The path must start with `data.`.

**3. Reference the current item**

In list item text, reference fields on the current item as `{{$.item.name}}` and `{{$.item.price}}`.

Given this Send API payload:

```json Send request lines highlight={6-10} theme={null}
{
  "message": {
    "to": { "user_id": "user_123" },
    "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    "data": {
      "order_items": [
        { "name": "Wireless Mouse", "quantity": 1, "price": "$29.99" },
        { "name": "USB-C Hub", "quantity": 2, "price": "$44.99" },
        { "name": "Laptop Stand", "quantity": 1, "price": "$59.99" }
      ]
    }
  }
}
```

Set the data path to `data.order_items`, then use `{{$.item.name}}`, `{{$.item.quantity}}`, and `{{$.item.price}}` in your list item text. Courier expands the list at send time, one item per array entry.

![Preview showing expanded list items from a looped data array](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-list-preview.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=0710eecbb4f0989c9125b9d7892cd73e)

List Loop Preview

A data path must start with `data.` and point to an array. Design Studio validates it against your [test event](https://www.courier.com/docs/design/templates/overview.md) data, so you catch mismatches before sending.

At render time, Courier's [loop evaluation](https://www.courier.com/docs/design/elemental/control-flow.md#loop) expands every iteration into one list block, so spacing and formatting stay consistent. For loop logic the List block doesn't support (nested loops, conditional items, custom markup), use an [HTML block](#html) with raw Handlebars.

## Columns

A column block starts as a two-column row with equal widths. Each cell is an independent container that accepts any block type, including nested columns.

Select the column block to configure it:

* **Columns count**: choose 1, 2, 3, or 4 columns.
* **Frame**: horizontal and vertical padding (pixels) and background color for each cell.
* **Border**: width, radius, and color for each cell.
* **Conditions**: show or hide the block based on profile or data values.

Frame and border settings apply per cell, so you can style each column independently.

![Column layout settings panel in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-column-cell-settings.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=d5b464554089afd831e5868f508e27de)

Column Layout Settings

Columns render differently per channel:

| Channel | Behavior |
| - | - |
| **Email** | Full multi-column layout using MJML for maximum email client compatibility |
| **Push** | Columns stack vertically (single-column fallback) |
| **SMS** | Not applicable. Content renders as plain text |
| **In-App (Inbox)** | Full support with responsive behavior |

Mobile email clients usually stack columns vertically, so keep to 2 or 3 columns and write content that reads well both side by side and stacked.

## HTML

HTML gives you full control of your markup for custom tables, tracking pixels, or porting an existing HTML email into Courier. There are two ways to use it.

| Your goal | Use | How |
| - | - | - |
| Add one custom section alongside drag-and-drop blocks | Inline HTML block | Add an HTML block in Design Studio |
| Bring an existing full HTML email into Courier | Whole-email HTML | Set `raw.html` on the email channel |
| Add HTML to a template programmatically (API) | Either | A `type: "html"` element inside a channel for a section, or `raw.html` on the email channel for a full document |

### Add an inline HTML block

The HTML block gives you a code editor in the right panel. Enter standard HTML (like `<div>`, `<table>`, or `<img>`) and inline CSS. Your changes appear in the canvas preview as you type.

![HTML block in Design Studio](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-custom-code-new.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=357dd49ae1e721e8f9c8d58d5c24f85e)

HTML Block

**An inline HTML block is a fragment, not a full page.** Leave out `<!DOCTYPE html>`, `<html>`, `<head>`, and `<body>`, because Courier composes your markup alongside the other blocks. For a full document, use [whole-email HTML](#send-a-full-html-email).

The expand icon in the editor's top-right corner opens a larger window.

### Variables and Handlebars

HTML blocks support [variables](https://www.courier.com/docs/design/templates/variables.md) in `{{variable}}` syntax and every [Handlebars helper](https://www.courier.com/docs/design/templates/variables.md), including `{{#if}}` for conditionals and `{{#each}}` for arrays. Inside an inline HTML block, Handlebars resolve automatically, with no transformer to configure.

This is the place for helper expressions. A rich-text block turns `{{` into a variable chip, so a helper call typed there is flagged invalid. An HTML block takes raw Handlebars as written.

```handlebars theme={null}
<ul>
{{#each data.items}}
  <li>{{this.name}}: {{this.price}}</li>
{{/each}}
</ul>
```

Use this for loop structures beyond the [List block's Loop on feature](#lists), such as nested loops or fully custom markup.

![Handlebars and variables in HTML block](https://mintcdn.com/courier-4f1f25dc/fN1MbwzHtG3Vhos5/assets/designer-v2-custom-code-rendered-handlebars.webp?fit=max\&auto=format\&n=fN1MbwzHtG3Vhos5\&q=85\&s=7d58900f29fddd2f5da8cd1165c44a67)

Handlebars Example

Variables and Handlebars expressions resolve on send, so [preview mode](https://www.courier.com/docs/design/templates/overview.md) shows the raw syntax rather than sample values.

### Send a full HTML email

To use a complete HTML document, put it on the email [channel](https://www.courier.com/docs/design/elemental/elements/channel.md) node's `raw.html`. Declare the `handlebars` transformer so your `{{variables}}` resolve. The `meta` title sets the subject line, and `raw.html` replaces that channel's rendered body.

```json theme={null}
{
  "content": {
    "version": "2022-01-01",
    "elements": [
      {
        "type": "channel",
        "channel": "email",
        "elements": [
          { "type": "meta", "title": "Your order confirmation" }
        ],
        "raw": {
          "transformers": ["handlebars"],
          "html": "<!DOCTYPE html><html><body><h1>Hi {{name}}</h1><p>Your order shipped.</p></body></html>"
        }
      }
    ]
  }
}
```

This shape works with [`POST /notifications`](https://www.courier.com/docs/api-reference/templates/create-notification-template) and [`PUT /notifications/{id}/content`](https://www.courier.com/docs/api-reference/templates/replace-notification-content), and renders your markup as written.

> [!NOTE]
>
> To add an inline HTML block over the API, put a `type: "html"` element inside the channel's `elements`. [`POST /notifications`](https://www.courier.com/docs/api-reference/templates/create-notification-template) and [`PUT /notifications/{id}/content`](https://www.courier.com/docs/api-reference/templates/replace-notification-content) both accept it. Use it for a fragment, and `raw.html` for a full document.
