# Upsert one language of a draft `PUT /v1/email/templates/{template_ref}/versions/{version_id}/languages/{language}` Saves one language's content on the template's draft, creating that language if the draft does not have it yet and replacing it in full if it does. Send the same content twice and the draft ends up the same way, so a sync job or CI run needs one call rather than a create-or-edit decision. Saving one language leaves every other language untouched, so a template with many languages can be edited a language at a time. Send the `revision` you last read to have a concurrent edit rejected with a `409` `conflict_error` instead of silently overwritten. Only a draft can be saved: addressing a published version returns a `422` `validation_error`, because a published version never changes. A template holds at most 25 languages. ## Code samples ### CLI ```sh bird email templates versions languages set \ --html '

Hi {{ bird.contact.first_name }}

' \ --preview-text '{{ bird.contact.first_name }}, your order is on its way' \ --subject 'Welcome to Acme, {{ bird.contact.first_name }}!' ``` ### cURL ```sh curl -X PUT "https://us1.platform.bird.com/v1/email/templates/{template_ref}/versions/{version_id}/languages/{language}" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "subject": "Welcome to Acme, {{ bird.contact.first_name }}!", "preview_text": "{{ bird.contact.first_name }}, your order is on its way", "html": "

Hi {{ bird.contact.first_name }}

" }' ``` ## Example response `200` ```json { "language": "pt-BR", "content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "template_ref": "emt_01krdgeqcxet5s7t44vh8rt9mg", "version_id": "emv_01krdgeqcxet5s7t44vh8rt9mg", "compatibility_severity": "warning", "next": [ { "kind": "operation" } ], "compatibility": [ { "rule_id": "css_display_flex_grid", "severity": "warning", "language": "pt-BR", "field": "html", "message": "`display: flex` and `grid` don't work in Outlook (Windows/Windows Mail).", "fix": "Use tables for layout.", "partial": "Partial support for `display: flex` and `grid` in Gmail (iOS/Android).", "line": 14, "column": 6, "match": "display: flex", "unsupported_clients": [ { "family": "outlook", "platforms": [ "windows", "windows_mail" ] } ], "partial_clients": [ { "family": "outlook", "platforms": [ "windows", "windows_mail" ] } ] } ] } ``` ## Path parameters - `template_ref` (string): The template's id (`emt_…`) or slug. On read, a built-in `system` template's `bird_` slug also resolves here. Writing or removing a language requires a workspace template, because a `system` template has no draft to edit and returns `404` `not_found_error`. - `version_id` (string) - `language` (string) ## Request body - `subject` (string, required): The email subject line for this language. - `preview_text` (string): The line an inbox shows after the subject in the message list. Leave it out and the inbox shows the opening words of the body instead. - `html` (string): The HTML body for this language. - `text` (string): The plain-text body for this language. Omit it and a plain-text alternative is derived from the HTML when you submit. - `revision` (integer): The revision you last read for this language, to detect a concurrent edit. The save is rejected with a conflict if the language moved on since. Omit it to save unconditionally. Creating a language does not need one. ## Response body - `language` (string, required): The language that was saved, in its canonical form. Send a tag in any casing and this reports the form the template stores. - `revision` (integer, required): This language's new revision. Send it back on your next save of this language so a concurrent edit is caught instead of silently overwritten. - `draft_revision` (integer, required): The draft's new revision. Saving a language moves it, so any template update you make next must send this value instead of the revision you read before the save. - `content_hash` (nullable string): A hash over the language's content as saved, prefixed with the algorithm that produced it (`sha256:`), so the algorithm can change without the field becoming ambiguous. It tells you whether a language differs without transferring the content, and is comparable only within one version of this API. - `updated_at` (nullable string): When this language was saved. - `template_ref` (string, required): The template this save addressed. - `version_id` (string, required): The draft this save wrote to. - `compatibility_severity` (string, required) The worst severity across every finding the response was computed from, which is the authoritative reading: a response that caps how many findings it lists still accounts here for the ones it left out. Each response's `compatibility` says which content it covered. - `problem`: at least one finding is a `problem`. - `warning`: every finding is a `warning`. - `none`: there are no findings. Possible values: `problem`, `warning`, `none` - `next` (array of object) What to do next with this save. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions. A `problem` in `compatibility` routes back to this same write, with the identifiers to address it already on this response; a `warning` says what degrades and leaves the draft as it is. - `next.kind` (string, required) What you do about this step. - `operation`: call the operation named in `operation`, then read again. - `external`: act somewhere this API does not reach, then read again. - `wait`: nothing is asked of you, so read again later. - `terminal`: nothing you do resolves this, so stop retrying. Tolerate a value you do not recognize: show the `description` and offer no action. Possible values (may grow over time): `operation`, `external`, `wait`, `terminal` - `next.description` (string, required): A short, human-readable label for the step, suitable for display. - `next.operation` (string): The operationId to call. Present only when `kind` is `operation`. The operation's own schema says how to call it; this says only which one, and what to address it with. - `next.params` (object): The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here. - `next.url` (string): A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal. - `compatibility` (array of object, required): What the HTML you just saved uses that mail clients remove, ignore, or render inconsistently, in the order the patterns appear. Empty when nothing is worth reporting. Advisory: the language was saved either way, and a finding never refuses a write. Line and column count in the HTML as saved, which the language read returns as `content.html`. A partial update reports on the language in full rather than on the fields it carried, so it reads the same as the read of the same language. At most 200 findings come back, the first 200 in source order; `compatibility_severity` is derived from every finding the HTML produced, including any beyond those 200. - `compatibility.rule_id` (string, required) The rule that produced this finding. Possible values (may grow over time): `html_script`, `html_event_handlers`, `html_embedded_content`, `html_linked_stylesheet`, `css_at_import`, `html_form`, `html_svg`, `html_media`, `css_display_flex_grid`, `css_position_fixed_sticky`, `css_variables_no_fallback`, `css_viewport_units`, `html_button`, `css_math_functions`, `css_modern_color`, `html_web_page_markup` - `compatibility.severity` (string, required) What a finding costs you. - `problem`: the pattern does nothing at all. The client removes the markup, never loads the stylesheet carrying it, or will not operate the control. Where a finding names clients, that is what happens in those clients. - `warning`: it does something, but not what you wrote. Neither one refuses a save, a submit, or a send. Possible values: `problem`, `warning` - `compatibility.language` (nullable string, required): Which language's content this finding is in. Null when the call covered a single language. - `compatibility.field` (string, required): Which field of that language the finding is in. Always `html`; the subject and the plain-text body are not checked. - `compatibility.message` (string, required): What is wrong and which clients it affects, worded to show to whoever is authoring the template. It covers the rule's whole category rather than the exact text that matched, so a rule covering `