Update one language of a draft

PATCH

/v1/email/templates/{template_ref}/versions/{version_id}/languages/{language}

bird email templates versions languages update <template-ref> <version-id> <language> \
  --html '<h1>Hi {{ bird.contact.first_name }}</h1>' \
  --preview-text '{{ bird.contact.first_name }}, your order is on its way' \
  --subject 'Welcome to Acme, {{ bird.contact.first_name }}!'

curl -X PATCH "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": "<h1>Hi {{ bird.contact.first_name }}</h1>"
  }'

响应200

{
  "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"
          ]
        }
      ]
    }
  ]
}

Changes part of one language's content on the template's draft: send only the fields you are changing and the rest keep their current values. Use this to fix a subject line without resending a megabyte of HTML.

The language must already exist on the draft. A language it does not have returns a 404 not_found_error. Save the language's full content instead to create it.

Send the revision you last read to have a concurrent edit rejected with a 409 conflict_error. Only a draft can be edited. Addressing a published version returns a 422 validation_error.

参数

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

请求载荷

subject

string

A new email subject line for this language.

preview_text

nullable string

A new line for the inbox to show after the subject in the message list. Send null to clear it, and the inbox shows the opening words of the body instead.

html

string

A new HTML body for this language.

text

nullable string

A new plain-text body for this language. Send null to clear 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 edit is rejected with a conflict if the language moved on since. Omit it to apply the edit unconditionally.

响应载荷

language

string

必填

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

必填

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

必填

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

必填

The template this save addressed.

version_id

string

必填

The draft this save wrote to.

compatibility_severity

string

必填

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

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

必填

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

必填

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

必填

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

必填

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

必填

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

必填

Which language's content this finding is in. Null when the call covered a single language.

compatibility.field

string

必填

Which field of that language the finding is in. Always html; the subject and the plain-text body are not checked.

compatibility.message

string

必填

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 <video> and <audio> names both whichever one is on the line. Show fix and then partial after it.

compatibility.fix

nullable string

必填

What to use instead. Null when there is no drop-in alternative and the fix is a restructure.

compatibility.partial

nullable string

必填

Which clients support the feature only partly. Null when no client's support is partial.

compatibility.line

integer

必填

The 1-based line the pattern is on, in the HTML the containing response's compatibility says it covered.

compatibility.column

integer

必填

The 1-based column the pattern starts at, on that line.

compatibility.match

string

必填

The source text that matched, starting at line and column: the smallest span that identifies what is wrong. Never the enclosing line. For a finding on a whole element, the span runs from the opening tag through the close tag, because the client drops the element's content along with its markup. Cut at 256 characters, so an element holding a long body is quoted from its start rather than in full.

compatibility.unsupported_clients

array of object

必填

Every client family that does not support the feature at all, in alphabetical order by each entry's family. Empty on a finding whose message, fix, and partial name no client. message names at most four families; this names all of them.

显示子属性

compatibility.unsupported_clients.family

string

必填

Which mail client a finding applies to. A finding's message names at most Apple Mail, Gmail, Outlook, and Yahoo; its unsupported_clients and partial_clients name every client affected.

gmail: Gmail
outlook: Outlook
yahoo: Yahoo
apple_mail: Apple Mail
aol: AOL
thunderbird: Mozilla Thunderbird
samsung_email: Samsung Email
sfr: SFR
orange: Orange
protonmail: ProtonMail
hey: HEY
mail_ru: Mail.ru
fastmail: Fastmail
laposte: LaPoste.net
gmx: GMX
web_de: WEB.DE
ionos_1and1: 1&1
wp_pl: WP.pl

Possible values (may grow over time): gmail, outlook, yahoo, apple_mail, aol, thunderbird, samsung_email, sfr, orange, protonmail, hey, mail_ru, fastmail, laposte, gmx, web_de, ionos_1and1, wp_pl

compatibility.unsupported_clients.platforms

array of string

必填

Which of the family's platforms this applies to, in alphabetical order.

compatibility.partial_clients

array of object

必填

Every client family that renders something other than what you wrote, in alphabetical order by each entry's family. Empty when no client's support is partial, which is also when partial is null. partial names at most four families; this names all of them.

显示子属性

compatibility.partial_clients.family

string

必填

Which mail client a finding applies to. A finding's message names at most Apple Mail, Gmail, Outlook, and Yahoo; its unsupported_clients and partial_clients name every client affected.

gmail: Gmail
outlook: Outlook
yahoo: Yahoo
apple_mail: Apple Mail
aol: AOL
thunderbird: Mozilla Thunderbird
samsung_email: Samsung Email
sfr: SFR
orange: Orange
protonmail: ProtonMail
hey: HEY
mail_ru: Mail.ru
fastmail: Fastmail
laposte: LaPoste.net
gmx: GMX
web_de: WEB.DE
ionos_1and1: 1&1
wp_pl: WP.pl

Possible values (may grow over time): gmail, outlook, yahoo, apple_mail, aol, thunderbird, samsung_email, sfr, orange, protonmail, hey, mail_ru, fastmail, laposte, gmx, web_de, ionos_1and1, wp_pl

compatibility.partial_clients.platforms

array of string

必填

Which of the family's platforms this applies to, in alphabetical order.

Update one language of a draft

相关资源