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. 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 commands, the email_blocks_* tools on the MCP server, and email.blocks in the TypeScript, Python, Go, and PHP SDKs. Request and response schemas are in the API reference. The dashboard has no block editor yet; see 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 shows when each kind of send takes a new revision.
- Languages match exactly. A
pt-BRtemplate language links only a publishedpt-BRblock language;ptdoes not stand in for it. - Writes send the revision you last read. The block's
revision, frombird email blocks get, guards metadata updates, such as renaming or archiving, and duplication. Each language's draftrevision, frombird email blocks languages get, guards saves and publications of that language. A stale revision returns409. A published revision'sversion_numbercounts 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_managementaccess: read access for reads and validation, and write access for every other block and template operation. See authentication. A barebird auth logingrants 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.
- 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 asus1for abk_us1_key. The examples write the block ID as$BLOCK_ID,{block_id}, or<block-id>; use theidthat 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:
<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
langon the<td>to the block language. A French copy of this footer needslang="fr". - The cell sets its own typography. Its
stylesets each offont-family,font-sizein pixels,font-style,font-weight,line-height,letter-spacing,text-align(left,right,center, orjustify),text-transform,color,margin, andpaddingonce, so the section looks the same in every template that links it. A value such asinherit, which takes the template's value, is refused, and so is thefontshorthand: set each property on its own. - The section is self-contained. It has no
<html>,<body>,<style>, script, or form element, and noclassoridattribute that a template's stylesheet could select. Sizes usepx,em, or percentages, not root-relative units such asrem, and styles cannot read CSS custom properties withvar(). Images and links use hosted URLs, becausedata:andjavascript: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 orstylevalue, and each branch holds complete elements; an output can still write an attribute value, as inhref="{{ 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
{{or{%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 entirehrefof 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. 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.
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:
jq -n --rawfile html footer.html \
'{name: "Legal footer", source_language: "en", fragment: {serializer_version: 2, fragment_html: $html}}' > block.jsonValidate 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:
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:
// 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);# Requires email_management:read permission in the target workspace.
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>'
)
result = client.email.blocks.validate(
language="en",
fragment={"serializer_version": 2, "fragment_html": section},
)
print(result.text)// Requires email_management:read permission in the target workspace.
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>`
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
result, err := client.Email.Blocks.Validate(context.Background(), bird.EmailBlocksValidateParams{
Language: "en",
Fragment: bird.EmailBlockFragment{SerializerVersion: 2, FragmentHtml: section},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text)// Requires email_management:read permission in the target workspace.
$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>';
$params = (new \MessageBird\Wire\Model\EmailBlockFragmentValidationRequest())
->setLanguage('en')
->setFragment((new \MessageBird\Wire\Model\EmailBlockFragment())
->setSerializerVersion(2)
->setFragmentHtml($section));
$result = $bird->email->blocks->validate($params);
echo $result->getText();bird email blocks validate --body-file - <<'JSON'
{
"language": "en",
"fragment": {
"serializer_version": 2,
"fragment_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: 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;\">Your disclosure text.</p></td></tr></tbody></table>"
}
}
JSONcurl -X POST "https://{region}.platform.bird.com/v1/email/blocks/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"language": "en",
"fragment": {
"serializer_version": 2,
"fragment_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: 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;\">Your disclosure text.</p></td></tr></tbody></table>"
}
}'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:
bird email blocks create --body-file block.jsonThe SDK and HTTP samples send a short starter section in place of the file:
// 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);# Requires email_management:write permission in the target workspace.
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>'
)
block = client.email.blocks.create(
name="Legal footer",
source_language="en",
fragment={"serializer_version": 2, "fragment_html": section},
)
print(block.id, block.revision)// Requires email_management:write permission in the target workspace.
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>`
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
block, err := client.Email.Blocks.Create(context.Background(), bird.EmailBlocksCreateParams{
Name: "Legal footer",
SourceLanguage: "en",
Fragment: &bird.EmailBlockFragment{SerializerVersion: 2, FragmentHtml: section},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(block.Id, block.Revision)// Requires email_management:write permission in the target workspace.
$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>';
$params = (new \MessageBird\Wire\Model\EmailBlockCreate())
->setName('Legal footer')
->setSourceLanguage('en')
->setFragment((new \MessageBird\Wire\Model\EmailBlockFragment())
->setSerializerVersion(2)
->setFragmentHtml($section));
$block = $bird->email->blocks->create($params);
echo $block->getId(), ' ', $block->getRevision();bird email blocks create 'Legal disclosure' --body-file - <<'JSON'
{
"name": "Legal disclosure",
"source_language": "en",
"fragment": {
"serializer_version": 2,
"fragment_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: 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;\">Your disclosure text.</p></td></tr></tbody></table>"
}
}
JSONcurl -X POST "https://{region}.platform.bird.com/v1/email/blocks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Legal disclosure",
"source_language": "en",
"fragment": {
"serializer_version": 2,
"fragment_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: 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;\">Your disclosure text.</p></td></tr></tbody></table>"
}
}'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 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:
jq -n --rawfile html footer.fr.html \
'{revision: 0, fragment: {serializer_version: 2, fragment_html: $html}}' > fr.jsonbird email blocks languages set "$BLOCK_ID" fr --body-file fr.jsoncurl -X PUT "https://{region}.platform.bird.com/v1/email/blocks/$BLOCK_ID/languages/fr" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @fr.jsonThe 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:
// 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);# Requires email_management:write permission in the target workspace.
block_id = "ebl_01krdgeqcxet5s7t44vh8rt9mg"
draft = client.email.blocks.languages.get(block_id, "en")
submission = client.email.blocks.publish(
block_id,
languages=[{"language": "en", "revision": draft.revision}],
)
print(submission.status, submission.published_revisions)// Requires email_management:write permission in the target workspace.
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
blockID := "ebl_01krdgeqcxet5s7t44vh8rt9mg"
draft, err := client.Email.Blocks.Languages.Get(ctx, blockID, "en")
if err != nil {
log.Fatal(err)
}
submission, err := client.Email.Blocks.Publish(ctx, blockID, bird.EmailBlocksPublishParams{
Languages: []bird.EmailBlockPublishLanguage{{Language: "en", Revision: draft.Revision}},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(submission.Status, submission.PublishedRevisions)// Requires email_management:write permission in the target workspace.
$blockId = 'ebl_01krdgeqcxet5s7t44vh8rt9mg';
$draft = $bird->email->blocks->languages->get($blockId, 'en');
$params = (new \MessageBird\Wire\Model\EmailBlockPublish())
->setLanguages([
(new \MessageBird\Wire\Model\EmailBlockPublishLanguage())
->setLanguage('en')
->setRevision($draft->getRevision()),
]);
$submission = $bird->email->blocks->publish($blockId, $params);
echo $submission->getStatus();bird email blocks publish <block-id> --body-file - <<'JSON'
{
"languages": [
{
"language": "en",
"revision": 2
}
]
}
JSONcurl -X POST "https://{region}.platform.bird.com/v1/email/blocks/{block_id}/publish" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"languages": [
{
"language": "en",
"revision": 2
}
]
}'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, 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 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:
bird email blocks publish "$BLOCK_ID" --language en=2 --yes --idempotency-key "$(uuidgen)"curl -X POST "https://{region}.platform.bird.com/v1/email/blocks/$BLOCK_ID/publish" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"languages": [{"language": "en", "revision": 2}], "confirm": true}'Use a new key, because the confirmed publication is a different request from the one that was refused. See 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 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 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:
bird email templates versions languages get "$TEMPLATE_ID" "$DRAFT_VERSION_ID" en --authoringcurl "https://{region}.platform.bird.com/v1/email/templates/$TEMPLATE_ID/versions/$DRAFT_VERSION_ID/languages/en?authoring=true" \
-H "Authorization: Bearer $TOKEN"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.
To add a link:
- 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. - Place an HTML comment in
htmlwhere the section goes. The comment's text isbird: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. - Add the same UUID to
shared_blocks.bindings, with the block's ID asblock_id. Setshared_blocks.versionto1. - Save the complete language with the
revisionyou read, or0for a language the draft does not have yet. Leavetextempty, because a language with links derives its plain text from the HTML with every section filled in:
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" }
}
}
}
EOFcurl -X PUT "https://{region}.platform.bird.com/v1/email/templates/$TEMPLATE_ID/versions/$DRAFT_VERSION_ID/languages/en" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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" }
}
}
}'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 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 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, 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 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 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:
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:
bird email blocks update "$BLOCK_ID" --revision 1 --archivedcurl -X PATCH "https://{region}.platform.bird.com/v1/email/blocks/$BLOCK_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"revision": 1, "archived": true}'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:
// 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);# Requires email_management:write permission in the target workspace.
source = client.email.blocks.get("ebl_01krdgeqcxet5s7t44vh8rt9mg")
copy = client.email.blocks.duplicate(source.id, revision=source.revision, name="Legal footer (EU)")
print(copy.id)// Requires email_management:write permission in the target workspace.
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
source, err := client.Email.Blocks.Get(ctx, "ebl_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
log.Fatal(err)
}
block, err := client.Email.Blocks.Duplicate(ctx, source.Id, bird.EmailBlocksDuplicateParams{
Revision: int(source.Revision),
Name: "Legal footer (EU)",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(block.Id)// Requires email_management:write permission in the target workspace.
$blockId = 'ebl_01krdgeqcxet5s7t44vh8rt9mg';
$source = $bird->email->blocks->get($blockId);
$params = (new \MessageBird\Wire\Model\EmailBlockDuplicate())
->setRevision($source->getRevision())
->setName('Legal footer (EU)');
$copy = $bird->email->blocks->duplicate($blockId, $params);
echo $copy->getId();bird email blocks duplicate <block-id> \
--name 'Legal disclosure copy' \
--revision 1curl -X POST "https://{region}.platform.bird.com/v1/email/blocks/{block_id}/duplicate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"revision": 1,
"name": "Legal disclosure copy"
}'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 | Fix what the message names, then validate again |
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 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 in the block, or add one to those templates first |
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 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 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: 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 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 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_version2. Version1is reserved for the dashboard's visual editor and returns422from any other caller. - Visual content stays in the dashboard. Outside the dashboard, a block language with
authoring_mode: visualcan 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
E04105and 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: author, preview, and publish the templates that link your blocks
bird email blocks: every block command and flag- API reference: request and response schemas for the 13 block operations
- Unsubscribe links: how the link a block carries works when mail is sent
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.