Create a content block

A content block is a reusable piece of an email that goes into a template’s slot: an ad, a product card, a featured article, a footer banner. One block can be used in many templates, and one template can use many blocks.

Blocks are shared across your workspace. Slot keys decide which blocks can go in which slot, and whoever sends picks from what’s allowed. See Slots.

In this section:

• Compose an email from a template — for whoever picks blocks and sends.
• Build a template — templates decide where blocks can go.
• Create a content block (this page) — the markup, slot keys, and block fields.

Before you begin#

• Some comfort with MJML, the same as for templates.
• A template with a slot to fill, or at least an agreement on the slot keys you’ll use. A block whose keys match no slot can’t be picked anywhere.
• For the API, keys need the templates:write scope to create or change blocks. See Create & use API keys.

Create a block#

In the sidebar, open Content→Blocks, then click New Block.

Three fields identify it:

• Block Name — what people see when they choose a block, such as Webinar banner.
• Slot Keys — which slots this block can go in. A slot takes the block when its Accepts list names any one of these keys. Keys use lowercase letters, numbers, dashes, and underscores.
• Slug — the short identifier for the block in API requests and files (block_id: webinar-banner). Leave it empty and it’s made from the name when you save.

Slot keys and tags are different things#

Both look like chips in the same editor, but they do unrelated jobs:

The difference matters in one more place: a Rotate slot’s Narrow by slot key works on slot keys, not tags. To build a rotating pool, give those blocks a shared slot key.

Write the block#

The content panel has the same three tabs as a template: MJML, Preview, and Plain text.

Write one or more <mj-section> elements, with no <mjml> wrapper, since the block sits inside the template. If you paste a full MJML document, the wrapper is trimmed off when you save.

Preview is a layout check. {{ param.* }} placeholders show as plain text, because a block’s values are filled in when someone picks it for a slot.

Plain text is optional on blocks. Leave it empty for purely visual pieces, like a button, an image, or a divider. Fill it in for anything with meaning, so people with text-only email apps get it too.

Set up block fields#

Blocks can have their own fields, set up on the Schema tab the same way as a template’s, including groups (+ Group) and repeating sections (+ Section). When someone picks the block for a slot, its fields appear under the picker for them to fill in. See Parameters.

The linter under the content panel works here too, with Declare this → and Declare all. Names that belong to merge tags get the same warning.

The template’s values flow in#

A block can use the template’s fields as well as its own. Write {{ param.brand_color }} in a block and it picks up the template’s value, with nothing set up on the block. That’s handy for brand values you don’t want to repeat everywhere. If the block and the template both have a field with that name, the block’s own value wins.

The block’s linter only knows the block’s own fields, so it flags a template field like this as undeclared. The block still saves and works; the warning only means the value comes from the template.

It doesn’t work the other way: a block’s fields belong to that block and the template can’t use them.

Make it available#

Under the content panel, Active — available for use in broadcasts controls whether the block is in use. The Blocks list shows each block as Active or Draft.

To retire a block without deleting it or disturbing the emails that already use it, clear Active. Rotate slots stop choosing it, and it’s no longer offered to API users.

Import and export#

Blocks export to a Markdown file and import back, like templates:

• Import .md on the Blocks list creates a new block.
• Export .md in the editor’s footer downloads the current one.

The header says kind: block, and slot keys are a comma-separated list:

---
kind: block
name: Webinar banner
slug: webinar-banner
slot_keys: cta, footer_promo
---

## MJML

```html
<mj-section>…</mj-section>
```

## Plain text

```
…
```

## Parameters

```json
[ … ]
```
Copy

Blocks have no ## Slots heading, since only templates decide where blocks go. ## Groups and ## Sections headings are accepted. Tags aren’t part of the file.

Change or delete a block#

You can edit a block at any time. When the change reaches an email depends on how the slot was filled:

• One block — the block is built into the email when the draft is saved, so a draft saved earlier keeps the old content until it’s saved again.
• Rotate and By rule — the block is chosen for each recipient as the email sends, so these pick up your edit as it stands when the broadcast goes out.

Broadcasts already sent never change; their content was settled when they went out.

The Usage card in the sidebar shows how many drafts and broadcasts use the block. You can’t delete a block while a draft uses it. To take it out of use without breaking anything, clear Active instead.

Common issues#

• The block isn’t offered for a slot. Its slot keys don’t match the slot’s Accepts list.
• A Rotate slot never picks the block. It isn’t Active, or it doesn’t have the slot key the slot is narrowed by.
• “Block not found” on a saved broadcast. The block was deleted, or its slot keys changed so it no longer fits. Whoever’s sending picks again from the slot’s card.
• A name gets a warning. It matches a merge tag, like first_name or email. Rename it.
• Delete is blocked. A draft still uses the block. Check the Usage card, or clear Active instead.

Good to know#

• Blocks are shared across the workspace. No template owns them; anything with matching slot keys is available everywhere.
• Blocks can’t contain slots. Only templates decide where blocks go.
• A rotating ad is several blocks that share a slot key.
• Merge tags work in blocks as they do in templates, using the same contact details, with no setup.