---
title: "Reusable email blocks"
description: "Write an email section such as a legal footer once as HTML, publish it, and link it into templates so a single change reaches every email that uses it."
canonical: "https://bird.com/docs/guides/email/reusable-blocks"
---

# Reusable email blocks

A reusable block is one email section, such as a legal footer, an address line, or a regulatory disclosure, that you write once and link into many [email templates](/docs/guides/email/templates). A template stores a link to the block instead of a copy of its HTML. When you publish a change to the block, every template that links it sends the new wording, without a new template version. Other email platforms call this a snippet, a partial, or a global content block. Use a block when the same section must stay identical across templates, and keep content that only one template uses in the template itself.

You create, validate, publish, and link blocks through `/v1/email/blocks`, the [`bird email blocks`](/docs/cli/reference/email-blocks) commands, the `email_blocks_*` tools on the [MCP server](/docs/ai/mcp-server), and `email.blocks` in the [TypeScript](/docs/sdks/typescript), [Python](/docs/sdks/python), [Go](/docs/sdks/go), and [PHP](/docs/sdks/php) SDKs. Request and response schemas are in the [API reference](/docs/api/reference/create-email-block). The dashboard has no block editor yet; see [Limits and current gaps](#limits-and-current-gaps).

## How blocks work

A block (`ebl_…`) has a name, an optional description, a source language, and one section per language. Each language has its own **draft**, which you edit, and its own published **revisions**, which sends use:

- **Saving a draft never publishes it.** A draft can hold unfinished content. Publishing a language checks its draft and freezes it as that language's next published revision.
- **A link follows the latest publication.** A template language links a block, never a specific revision. Mail fills the link with the block's latest published revision in the template's own language; [Update a published block](#update-a-published-block) shows when each kind of send takes a new revision.
- **Languages match exactly.** A `pt-BR` template language links only a published `pt-BR` block language; `pt` does not stand in for it.
- **Writes send the revision you last read.** The block's `revision`, from `bird email blocks get`, guards metadata updates, such as renaming or archiving, and duplication. Each language's draft `revision`, from `bird email blocks languages get`, guards saves and publications of that language. A stale revision returns `409`. A published revision's `version_number` counts that language's publications.

Each block language also reports an `authoring_mode`. Sections you write through the API, CLI, MCP, or SDKs report `html`. The value `visual` is reserved for sections built in the dashboard's visual editor, which only the dashboard edits.

## Before you start

- **Access.** Use an API key or CLI login with `email_management` access: read access for reads and validation, and write access for every other block and template operation. See [authentication](/docs/guides/authentication). A bare `bird auth login` grants read access only; a CLI command that needs write access prints the exact login command to run.
- **A template edited as HTML.** Linking a block needs a template whose language you edit as HTML. A template language built in the dashboard's visual editor cannot link blocks outside the dashboard; see [Limits and current gaps](#limits-and-current-gaps).
- **Hosts and IDs in the examples.** The cURL examples read an API key from `$TOKEN`. Replace `{region}` in the host with the region in your key's prefix, such as `us1` for a `bk_us1_` key. The examples write the block ID as `$BLOCK_ID`, `{block_id}`, or `<block-id>`; use the `id` that creating the block returns.

## Write a block section

A block holds one self-contained section: a single `<table role="presentation">` with one `<tbody>`, one `<tr>`, and one `<td>`. Everything the recipient sees goes inside that cell. This legal footer, saved as `footer.html`, is a complete section:

```html
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">
  <tbody>
    <tr>
      <td
        lang="en"
        style="font-family: Arial, sans-serif; font-size: 12px; font-style: normal; font-weight: normal; line-height: 18px; letter-spacing: normal; text-align: center; text-transform: none; color: #6b7280; margin: 0; padding: 24px 16px;"
      >
        <p style="margin: 0 0 8px;">Acme Inc., 100 Main Street, Springfield, IL 62701</p>
        <p style="margin: 0;">
          You receive this email because you subscribed to Acme news.
          <a href="{{ bird.unsubscribe_url }}" style="color: #6b7280;">Unsubscribe</a>
        </p>
      </td>
    </tr>
  </tbody>
</table>
```

A section must follow these rules to publish, and validation names the rule a section breaks:

- **The cell names its language.** Set `lang` on the `<td>` to the block language. A French copy of this footer needs `lang="fr"`.
- **The cell sets its own typography.** Its `style` sets each of `font-family`, `font-size` in pixels, `font-style`, `font-weight`, `line-height`, `letter-spacing`, `text-align` (`left`, `right`, `center`, or `justify`), `text-transform`, `color`, `margin`, and `padding` once, so the section looks the same in every template that links it. A value such as `inherit`, which takes the template's value, is refused, and so is the `font` shorthand: set each property on its own.
- **The section is self-contained.** It has no `<html>`, `<body>`, `<style>`, script, or form element, and no `class` or `id` attribute that a template's stylesheet could select. Sizes use `px`, `em`, or percentages, not root-relative units such as `rem`, and styles cannot read CSS custom properties with `var()`. Images and links use hosted URLs, because `data:` and `javascript:` URLs are refused.
- **The markup parses as written.** Close every element, give each nested table its own `<tbody>`, and avoid markup a browser would repair, such as a `<div>` inside a `<p>`.
- **Outlook conditional comments are complete.** Each `<!--[if mso]>…<![endif]-->` comment holds complete markup. A `<!--[if !mso]><!-->…<!--<![endif]-->` span, which every client except Outlook shows, is accepted when its content is balanced and holds no other conditional comment.
- **Liquid stays inside the cell.** Output such as `{{ order_id }}` and tags such as `{% if %}` work inside the cell. A tag goes around whole elements, never inside an attribute or `style` value, and each branch holds complete elements; an output can still write an attribute value, as in `href="{{ offer_url }}"`. A block cannot use `{% assign %}`, `{% capture %}`, `{% increment %}`, or `{% decrement %}`, because a block shares its variables with every template that links it.
- **Entities do not hide Liquid.** We derive the plain-text version from the section's HTML and decode entities on the way, so `&#123;&#123;` or `&#123;%` in the HTML becomes Liquid in that text, and validation refuses it unless it is valid Liquid that sets no variable.
- **The unsubscribe link stands alone where every client shows it.** `{{ bird.unsubscribe_url }}` goes in as bare text or as the entire `href` of a link, as in the footer above, with nothing added before or after it, and outside any `<!--[if !mso]><!-->` span.
- **A block cannot link another block.** A section cannot contain the `bird:shared-block:` marker comment that templates use to link blocks.

Variables the section uses become inputs of every template that links it, so senders supply them the way they supply the template's own [parameters](/docs/guides/email/templates#personalizing-with-variables). We work out a section's inputs from the section on its own, so a name the template sets with `{% assign %}` or as a `{% for %}` loop variable still becomes an input the sender must supply. When the email renders, though, the section sits inside the template, and a value the template sets before or around it replaces the sender's value. Give block inputs names the template does not set. A `bird.contact.*` attribute the section reads must be one of the built-in `first_name`, `last_name`, and `email` fields or a registered custom [contact property](/docs/guides/email/contacts#contact-properties).

The API takes the section as a JSON string in `fragment.fragment_html`, with `serializer_version` set to `2`, and stores it exactly as sent. To build a request body from `footer.html`, let `jq` escape it:

```bash
jq -n --rawfile html footer.html \
  '{name: "Legal footer", source_language: "en", fragment: {serializer_version: 2, fragment_html: $html}}' > block.json
```

## Validate a block section

Validation checks a section against the rules publication applies and returns the plain text derived from it. It saves nothing, so you can run it before you create the block and on every edit, for example in CI. This command checks `footer.html` as an English section:

```bash
jq -n --rawfile html footer.html \
  '{language: "en", fragment: {serializer_version: 2, fragment_html: $html}}' |
  bird email blocks validate --body-file -
```

The SDKs and the HTTP API take the same request. These samples validate a short starter section:

**TypeScript**

```typescript
// Requires email_management:read permission in the target workspace.
const section =
  '<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tbody><tr>' +
  '<td lang="en" style="font-family: Arial, sans-serif; font-size: 14px; font-style: normal; font-weight: normal; ' +
  'line-height: 20px; letter-spacing: normal; text-align: left; text-transform: none; color: #333333; margin: 0; padding: 16px;">' +
  '<p style="margin: 0;">Offer valid until {{ expiry_date }}.</p></td></tr></tbody></table>';
const result = await bird.email.blocks.validate({
  language: "en",
  fragment: { serializer_version: 2, fragment_html: section },
});
console.log(result.text);
```

Examples: [TypeScript](/docs/guides/email/reusable-blocks.ts.md) · [Python](/docs/guides/email/reusable-blocks.py.md) · [Go](/docs/guides/email/reusable-blocks.go.md) · [PHP](/docs/guides/email/reusable-blocks.php.md) · [CLI](/docs/guides/email/reusable-blocks.cli.md) · [MCP](/docs/guides/email/reusable-blocks.mcp.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

A valid section returns `200` with its plain text in `text`. For the footer, `text` holds the address line, the subscription sentence, and `Unsubscribe ({{ bird.unsubscribe_url }})`. A section that breaks a rule returns `422` `validation_error` with a `details` entry for `fragment_html` that says what to change, such as `The section's content cell must set lang="fr" to match this block language`. Validation checks contact properties only when your key or login also has `email_marketing` read access; publication checks them either way.

## Create a block

Create the block with its name, its source language, and the section for that language. With the `block.json` file from [Write a block section](#write-a-block-section):

```bash
bird email blocks create --body-file block.json
```

The SDK and HTTP samples send a short starter section in place of the file:

**TypeScript**

```typescript
// Requires email_management:write permission in the target workspace.
const section =
  '<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tbody><tr>' +
  '<td lang="en" style="font-family: Arial, sans-serif; font-size: 14px; font-style: normal; font-weight: normal; ' +
  'line-height: 20px; letter-spacing: normal; text-align: left; text-transform: none; color: #333333; margin: 0; padding: 16px;">' +
  '<p style="margin: 0;">Offer valid until {{ expiry_date }}.</p></td></tr></tbody></table>';
const block = await bird.email.blocks.create({
  name: "Legal footer",
  source_language: "en",
  fragment: { serializer_version: 2, fragment_html: section },
});
console.log(block.id, block.revision);
```

Examples: [TypeScript](/docs/guides/email/reusable-blocks.ts.md) · [Python](/docs/guides/email/reusable-blocks.py.md) · [Go](/docs/guides/email/reusable-blocks.go.md) · [PHP](/docs/guides/email/reusable-blocks.php.md) · [CLI](/docs/guides/email/reusable-blocks.cli.md) · [MCP](/docs/guides/email/reusable-blocks.mcp.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

The response carries the block's `id` (`ebl_…`), which the commands below read from `$BLOCK_ID`, and the block's `revision`. The block starts unpublished, with its source-language draft at `revision` 1. Create accepts unfinished content, so a successful create does not mean the section can publish; [validate it](#validate-a-block-section) first.

### Add a language to a block

To add a language, save a complete section for it with `revision` `0`. For French, save a copy of the footer with `lang="fr"` on its cell as `footer.fr.html`, then build the request body and save it:

```bash
jq -n --rawfile html footer.fr.html \
  '{revision: 0, fragment: {serializer_version: 2, fragment_html: $html}}' > fr.json
```

**CLI**

```cli
bird email blocks languages set "$BLOCK_ID" fr --body-file fr.json
```

Examples: [CLI](/docs/guides/email/reusable-blocks.cli.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

The response carries the new language's draft `revision`; publish the language with that revision. A block holds up to 25 languages.

## Publish a block

A publish request names each language once, with the draft `revision` you last read from `bird email blocks languages get`. The languages you name publish together or not at all:

**TypeScript**

```typescript
// Requires email_management:write permission in the target workspace.
const blockId = "ebl_01krdgeqcxet5s7t44vh8rt9mg";
const draft = await bird.email.blocks.languages.get(blockId, "en");
const submission = await bird.email.blocks.publish(blockId, {
  languages: [{ language: "en", revision: draft.revision }],
});
console.log(submission.status, submission.published_revisions);
```

Examples: [TypeScript](/docs/guides/email/reusable-blocks.ts.md) · [Python](/docs/guides/email/reusable-blocks.py.md) · [Go](/docs/guides/email/reusable-blocks.go.md) · [PHP](/docs/guides/email/reusable-blocks.php.md) · [CLI](/docs/guides/email/reusable-blocks.cli.md) · [MCP](/docs/guides/email/reusable-blocks.mcp.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

In the CLI, you can name the languages with flags instead of a body file: `bird email blocks publish "$BLOCK_ID" --language en=1 --language fr=1`. The response has `status` `published` and lists `published_revisions`, one per language. Each published language's `published_revision_id` now points at its new revision, and templates can link the block in that language.

A publication is refused with `409` `conflict_error` if a draft was saved after you read it, and with `422` `validation_error` if a draft has no unpublished changes or its section breaks a rule. Two more checks protect templates that already link the block.

### Confirm a publication that adds sender inputs

If the new content uses a variable the sender supplies, and the language's current publication did not use it, sends of live templates that link the block start requiring that value, and a send that leaves it out is refused. Publishing is therefore refused with `409` and the error code [`E04105`](/docs/api/errors/E04105), whose message names each new input and up to 10 affected templates. Values under `bird.`, such as contact properties, do not trigger it, because we fill them.

Update those senders first, so their sends and [broadcasts](/docs/guides/email/broadcasts) supply the new value. A broadcast that sets `template.parameter_overrides` must supply the value in `template.parameters` when the template's default language links the block; when only the broadcast's selected language links it, that language's override can supply it instead. An override set to `null` for the name replaces the shared value, so remove the override or give it a value. Then repeat the same languages and revisions with `confirm` set to `true` (`--yes` in the CLI), under a new idempotency key:

**CLI**

```cli
bird email blocks publish "$BLOCK_ID" --language en=2 --yes --idempotency-key "$(uuidgen)"
```

Examples: [CLI](/docs/guides/email/reusable-blocks.cli.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

Use a new key, because the confirmed publication is a different request from the one that was refused. See [idempotency](/docs/guides/idempotency).

A scheduled broadcast takes the new content when it is prepared for sending, at its scheduled time, and fails if it then lacks the new input. Through the API, you can add the value to each scheduled broadcast before you publish, because a broadcast keeps a value its template does not use yet. The dashboard's broadcast composer shows the new input only after you publish, so if you update broadcasts there, first reschedule any that are due soon to leave time to add the value. After you publish, run [Validate an email broadcast](/docs/api/reference/validate-email-broadcast) on each affected broadcast. Updating a broadcast needs `email_marketing` write access, and validating one needs `email_marketing` and `email_management` read access.

### Keep the unsubscribe link

A marketing template's unsubscribe link can come from its own HTML or from a block it links. Sending counts a link only where every recipient gets it, outside any `{% if %}` or `{% for %}`, and refuses a marketing email without one. A publication that removes the link from a block is refused with `422` `validation_error`, naming up to 10 templates, when a live marketing template would have no other link. That check counts another linked block's link wherever the template places it, so before you remove the link, make sure each affected template keeps one outside any condition or loop. Keep the link in the block, or add one to those templates and publish them first. See [unsubscribe links](/docs/guides/email/unsubscribe-links) for how the link works.

## Link a block into a template

You link a block by saving a template's draft language with a marker comment where the section goes and a matching entry in `shared_blocks`. The block must be unarchived and published in the same language tag as the template language. The examples use `TEMPLATE_ID` and `DRAFT_VERSION_ID` for the template's `id` and `draft_version_id`, which `bird email templates get "$TEMPLATE_ID"` returns.

Start by reading the draft language with `authoring` set to `true`:

**CLI**

```cli
bird email templates versions languages get "$TEMPLATE_ID" "$DRAFT_VERSION_ID" en --authoring
```

Examples: [CLI](/docs/guides/email/reusable-blocks.cli.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

The response returns the HTML with any existing link markers, the `shared_blocks` map, `authoring_mode`, and the language `revision` to save with. If `authoring_mode` is `visual`, this language cannot link blocks outside the dashboard; see [Limits and current gaps](#limits-and-current-gaps).

To add a link:

1. Generate a lowercase UUID for the link, for example with `uuidgen | tr 'A-Z' 'a-z'`. Each link in a language has its own UUID.
2. Place an HTML comment in `html` where the section goes. The comment's text is `bird:shared-block:` followed by the UUID, with no spaces. Put it directly inside `<body>`, a `<div>`, or a table cell, where a table can go, not inside a paragraph or between a table's rows.
3. Add the same UUID to `shared_blocks.bindings`, with the block's ID as `block_id`. Set `shared_blocks.version` to `1`.
4. Save the complete language with the `revision` you read, or `0` for a language the draft does not have yet. Leave `text` empty, because a language with links derives its plain text from the HTML with every section filled in:

**CLI**

```cli
bird email templates versions languages set "$TEMPLATE_ID" "$DRAFT_VERSION_ID" en --body-file - <<'EOF'
{
  "subject": "Your order is confirmed",
  "html": "<!DOCTYPE html>\n<html>\n<body>\n<p>Thanks for your order, {{ first_name }}.</p>\n\u003c!--bird:shared-block:3f2b8c1e-5d4a-4e6b-9c7d-2a1f0e9b8c7d--\u003e\n</body>\n</html>\n",
  "text": "",
  "revision": 4,
  "shared_blocks": {
    "version": 1,
    "bindings": {
      "3f2b8c1e-5d4a-4e6b-9c7d-2a1f0e9b8c7d": { "block_id": "ebl_01krdgeqcxet5s7t44vh8rt9mg" }
    }
  }
}
EOF
```

Examples: [CLI](/docs/guides/email/reusable-blocks.cli.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

The examples write the comment's `<` and `>` as the JSON escapes `\u003c` and `\u003e`; either form saves the same HTML. The save replaces the whole language, so send every field it keeps, such as `preview_text`; a field you leave out is cleared. If the language already has custom plain text, add `"replace_custom_text": true` (`--replace-custom-text` in the CLI) to replace it in the same save. The response carries the language's new `revision` and the saved `shared_blocks`. A language links up to 100 sections.

To see the section in place, [preview](/docs/guides/email/templates#previewing-before-you-publish) the draft with `bird email templates preview "$TEMPLATE_ID" --language en`. The rendered HTML carries the block's published section where the marker was. Then submit the draft with `bird email templates versions submit "$TEMPLATE_ID" "$DRAFT_VERSION_ID"`. The published version keeps the links, and every [send with the template](/docs/guides/email/templates#sending-with-a-template) fills them.

To move a section, move its marker and keep its UUID. To add the same block twice, use a second UUID. To remove a link, delete both its marker and its binding. To remove every link, save HTML without markers and `"bindings": {}`.

## Read a linked template back

An ordinary read of a template language, or of a published version, returns the HTML with each block's current published section filled in, and reports `has_shared_blocks: true`. That HTML changes when a linked block is published. Copying it into another template creates independent content that no longer follows the block.

Read with `authoring` set to `true` whenever you plan to save the language. A save that changes the body of a linked language without `shared_blocks` is refused with [`E04109`](/docs/api/errors/E04109), so a sync job that writes back filled HTML cannot drop the links by accident. To change only the subject or preview text, a partial update (`bird email templates versions languages update`) with the language's `revision` needs no `shared_blocks`.

[Duplicating](/docs/api/reference/duplicate-email-template) a template keeps its links, and so does rolling back to an earlier version. A rollback restores the links, not earlier block content: the restored version sends each block's latest publication.

## Update a published block

To change a published block, read the language's draft with `bird email blocks languages get`, save the new section with `bird email blocks languages set` and that draft `revision`, validate it, and publish it again. Each publication reaches mail as follows:

| Where the template is used                                   | Block content it gets                                              |
| ------------------------------------------------------------ | ------------------------------------------------------------------ |
| Sends accepted after the publication                         | The new revision                                                   |
| Broadcasts prepared for sending after the publication        | The new revision, including broadcasts already scheduled before it |
| Broadcasts already prepared when you publish                 | The revision current when they were prepared                       |
| Messages accepted with `scheduled_at` before the publication | The revision current when the message was accepted                 |
| Messages already accepted or sent                            | Unchanged                                                          |
| Template previews and reads                                  | The new revision, from the next request                            |

A broadcast is prepared when its scheduled time arrives, or straight away when you send it now, and preparation freezes its content before delivery starts, so it keeps that revision through a pause. Some older broadcasts, scheduled before we froze broadcast content, can fill sections with the current revision again when resumed.

Because a block change reaches scheduled broadcasts, validate the section before you publish. A template preview fills each link with the block's published section, not its draft, so it shows the new wording only after you publish. To check the new section in place first, [preview](/docs/guides/email/templates#previewing-before-you-publish) the template with its content in the request and the new section's HTML where the marker goes.

To return to earlier wording, list the language's published revisions with `bird email blocks languages revisions list "$BLOCK_ID" en`, copy one back into the draft, and publish the draft:

```bash
bird email blocks languages set "$BLOCK_ID" en --revision 3 --from-revision-id ebr_01krdgeqcxet5s7t44vh8rt9mg
```

`--revision` is the draft revision you last read, and `--from-revision-id` is the published revision's `id`. Copying a revision changes only the draft; templates keep sending the current publication until you publish again. A language that was never published can be deleted with `bird email blocks languages delete "$BLOCK_ID" fr --yes`; the source language and published languages stay.

## Archive or duplicate a block

Archive a block that should not be linked anew. An archived block keeps filling every link that already exists, and you can still publish corrections to it. Linking it into another template is refused until you unarchive it. Blocks have no delete operation, so archive one you no longer use:

**CLI**

```cli
bird email blocks update "$BLOCK_ID" --revision 1 --archived
```

Examples: [CLI](/docs/guides/email/reusable-blocks.cli.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

Send the block's `revision` from `bird email blocks get`. Unarchive with `--archived=false` or `"archived": false`. The same update renames the block, edits its description, or changes its source language before its first publication. `bird email blocks list --archived=false` lists only active blocks.

Duplicate a block to start a variant, such as a regional footer. The copy gets every current draft, keeps each language's authoring mode, and starts unpublished with no history:

**TypeScript**

```typescript
// Requires email_management:write permission in the target workspace.
const source = await bird.email.blocks.get("ebl_01krdgeqcxet5s7t44vh8rt9mg");
const copy = await bird.email.blocks.duplicate(source.id, {
  revision: source.revision,
  name: "Legal footer (EU)",
});
console.log(copy.id);
```

Examples: [TypeScript](/docs/guides/email/reusable-blocks.ts.md) · [Python](/docs/guides/email/reusable-blocks.py.md) · [Go](/docs/guides/email/reusable-blocks.go.md) · [PHP](/docs/guides/email/reusable-blocks.php.md) · [CLI](/docs/guides/email/reusable-blocks.cli.md) · [MCP](/docs/guides/email/reusable-blocks.mcp.md) · [cURL](/docs/guides/email/reusable-blocks.curl.md)

## Troubleshoot block errors

| Error                                                              | Cause                                                                                      | What to do                                                                                                                                                                                  |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `409` `conflict_error` on a save, update, duplicate, or publish    | The block or language changed after you read it                                            | Read it again, reapply your change, and send the new `revision`                                                                                                                             |
| `422` `validation_error` naming `fragment_html`                    | The section breaks a [section rule](#write-a-block-section)                                | Fix what the message names, then validate again                                                                                                                                             |
| [`E04105`](/docs/api/errors/E04105) (`409`) on publish             | The new content requires inputs that live templates' senders do not supply yet             | Update those senders, then [publish again with `confirm`](#confirm-a-publication-that-adds-sender-inputs) under a new idempotency key                                                       |
| `422` naming templates that would lose their unsubscribe link      | The publication removes the only unsubscribe link from live marketing templates            | [Keep the link](#keep-the-unsubscribe-link) in the block, or add one to those templates first                                                                                               |
| [`E04110`](/docs/api/errors/E04110) on a block language save       | The language keeps the authoring mode it was created with, and the save uses the other one | Save HTML only to `html` languages. To write a visual section as HTML, create a new block                                                                                                   |
| [`E04108`](/docs/api/errors/E04108) on a template language save    | The template language was built in the visual editor                                       | If it links no blocks, an ordinary save without `shared_blocks` replaces its visual design with your HTML, and you can link blocks after that. To keep the design, edit it in the dashboard |
| [`E04109`](/docs/api/errors/E04109) on a template language save    | The language links blocks and the save changes its body without `shared_blocks`            | Read it with `authoring=true` and save the complete language with its markers, `shared_blocks`, and `revision`                                                                              |
| [`E04007`](/docs/api/errors/E04007): a linked block is unavailable | A new link names a block that is archived or not published in this exact language          | Publish the block in that language, unarchive it, or link another block                                                                                                                     |
| `422` naming a language's `html` or `shared_blocks`                | A marker is misplaced, malformed, repeated, or has no matching binding                     | Use one lowercase UUID per marker, match each marker to one binding, and place markers where a table can go                                                                                 |
| `422` naming `revision` on a linked save                           | The save that links blocks sends no `revision`                                             | Read the language with `authoring=true` and send its `revision`, or `0` for a new language                                                                                                  |
| `422` naming `replace_custom_text`                                 | The language has custom plain text and the save adds its first link                        | Add `"replace_custom_text": true` to replace the text with text derived from the HTML                                                                                                       |
| `422` naming `text`                                                | A save of a language with links sends plain text                                           | Send `text` as an empty string, or leave it out                                                                                                                                             |

[Error handling](/docs/guides/errors) covers how to branch on an error's `type` and `code`.

## Limits and current gaps

- **No block editor in the dashboard yet.** Until it arrives, author blocks and edit template languages that link them through the API, CLI, MCP, or SDKs. In the dashboard, a template language linked this way cannot have its body edited or serve as the source for **Add language**, and **Duplicate** on the template's details copies the filled HTML without its links; use the [duplicate operation](/docs/api/reference/duplicate-email-template) to copy a template with its links.
- **Broadcast views show current block content.** The dashboard's view of a sent broadcast's message, the preview before you resume a paused broadcast, and an API read of the template version a broadcast is fixed to all fill linked sections with each block's current publication. A broadcast keeps the revision it was prepared with, so these views can differ from what it delivered or will send after it resumes. Leave a paused broadcast paused unless you can confirm what its remaining recipients will receive.
- **HTML sections only outside the dashboard.** The API, CLI, MCP, and SDKs write sections with `serializer_version` `2`. Version `1` is reserved for the dashboard's visual editor and returns `422` from any other caller.
- **Visual content stays in the dashboard.** Outside the dashboard, a block language with `authoring_mode: visual` can be read, duplicated, or restored from a published revision, but not replaced with HTML. A visual template language cannot link blocks outside the dashboard. While it links none, an ordinary save replaces its visual design with your HTML, and the language can link blocks after that.
- **Sizes.** A block holds up to 25 languages. A section holds up to 524,288 characters, with elements nested up to 512 levels deep. A template language links up to 100 sections, and its HTML with every section filled in can be up to 524,288 characters. Saving, previewing, and submitting a template draft check that size; publishing a block does not. If a block publication pushes a linked draft language past it, reads and previews of that draft language fail until you publish a shorter version of the block.
- **No usage listing.** The API does not list which templates link a block. The `E04105` and unsubscribe refusals name up to 10 affected templates.
- **No section preview.** Preview a template that links the block to see the section rendered.

## Next steps

- [Email templates](/docs/guides/email/templates): author, preview, and publish the templates that link your blocks
- [`bird email blocks`](/docs/cli/reference/email-blocks): every block command and flag
- [API reference](/docs/api/reference/create-email-block): request and response schemas for the 13 block operations
- [Unsubscribe links](/docs/guides/email/unsubscribe-links): how the link a block carries works when mail is sent

## Related resources

- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Email](/email-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=email)
