Get an email template preview
/v1/email/templates/{template_ref}/previewbird email templates preview <template-ref> --body-file - <<'JSON'
{
"content": {
"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>"
},
"parameters": {
"bird": {
"contact": {
"first_name": "Ada"
}
},
"animal": "otter"
},
"contact": "con_01krdgeqcxet5s7t44vh8rt9mg",
"language": "pt-BR",
"version": "emv_01krdgeqcxet5s7t44vh8rt9mg"
}
JSONcurl -X POST "https://us1.platform.bird.com/v1/email/templates/{template_ref}/preview" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": {
"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>"
},
"parameters": {
"bird": {
"contact": {
"first_name": "Ada"
}
},
"animal": "otter"
},
"contact": "con_01krdgeqcxet5s7t44vh8rt9mg",
"language": "pt-BR",
"version": "emv_01krdgeqcxet5s7t44vh8rt9mg"
}'{
"language": "pt-BR",
"variables": [
{
"type": "code"
}
],
"compatibility_severity": "warning",
"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"
]
}
]
}
]
}
Renders a template with the sample values you supply and returns the resulting subject, HTML, and plain-text bodies. Bird does not issue a recipient-specific unsubscribe URL in a preview. If you supply bird.unsubscribe_url in parameters, the preview renders your value; an empty link is not live. Bird adds unsubscribe content to marketing email at send time; transactional email gets no automatic unsubscribe footer. By default it renders the current draft, so you can check your changes before you submit it. Pass version to preview a specific published version instead; built-in system templates have no versions, so version on a bird_ template returns a validation error. Pass contact to see the email the way one of your contacts would receive it. Works for your workspace templates and built-in system templates. Sample parameters are capped at 16 KB once serialized, and personalization that is not valid or not supported returns a validation error naming what to fix.
The response also reports what the HTML uses that mail clients remove, ignore, or render inconsistently. Each finding in compatibility names the pattern, the line and column it sits on, and what to use instead, and compatibility_severity reduces them to one word for the whole body. It is advisory: the preview renders either way.
Parâmetros
template_refstringThe template to preview: a workspace template's id (emt_…) or slug, or a built-in system template's bird_ slug.
Corpo da requisição
contentRender this content rather than the template's stored draft. It is what an editor uses to show a change as it is made, since nothing has to be saved first.
The content is treated exactly as a draft would be: personalization is filled in the same way, a plain-text body is derived from the HTML when you omit it, and content that could not be published is refused with the same error. version asks for a published version's own content, so the two cannot be combined.
parametersSample values for the variables the template uses, for this one preview only. A variable takes its value under its own name. A bird. value nests to match the token, so {"bird": {"contact": {"first_name": "Ada"}}} fills {{ bird.contact.first_name }}.
A preview is more forgiving than a send: a parameter you leave out renders as empty here rather than being rejected. parameters is capped at 16 KB once serialized.
contactRender the template the way this contact would receive it. Every {{ bird.contact.… }} token takes its value from the contact's record, narrowed to the attributes the template reads and filled from each property's fallback_value where the contact holds no value: the same values a broadcast to this contact would send.
Values are read as the contact stands right now, so a preview reflects an edit to their record as soon as you make it. A bird.contact.… value you also pass in parameters wins for that one attribute, so you can preview a contact with one field changed without editing them.
languageWhich of the template's languages to render. Omit it to render the default language. When the template does not have the language you ask for, its own on_missing_language setting decides whether a close match is rendered instead or the request is rejected. It is the same choice the send makes.
versionPreview a specific published version by its id, instead of the current draft.
Payload de resposta
editor_urlOptional link to open the saved draft in the browser editor, in the language this preview rendered. Absent for built-in templates, published-version previews, and previews of unsaved content.
subjectThe rendered subject line. Null when the template has no subject.
htmlThe rendered HTML body. Null when the template has no HTML body.
textThe rendered plain-text body. Derived from the HTML when the template has no separate plain-text body, and null when it has neither.
languageThe language this preview rendered. It differs from the language you asked for when the template does not have that one and a close match was served instead.
variablesEvery input definition this content uses, in one list: the parameters you fill in
with parameters, and the values Bird fills in for each recipient. Read system
to tell them apart. This list covers only the language named by language. A
version read combines the inputs from every language the version holds. Preview
each language separately to see its own. You can nest sample values under bird
in preview parameters; sends reject that reserved namespace.
Mostrar atributos secundários
variables.keyThe key this slot is filled by. When system is true it is the reserved bird key or a dotted path beneath it, such as bird.contact.first_name, and naming it in a send is rejected. Otherwise, on email and SMS it is the key you set in the send's parameters object, and on WhatsApp the name you repeat on the matching parameter inside components, or, for a template whose placeholders are positional, the position itself as 1, 2 and so on.
variables.typeThe value type this slot accepts. Built-in SMS templates use typed slots (code, amount and the rest), each of which rejects a value that does not match its constraint. Email, WhatsApp and workspace SMS templates use text. Workspace SMS parameters must be scalar values. Open enum: treat an unrecognized value as a future type rather than an error.
Possible values (may grow over time): code, ttl, count, ref, date, date_time, amount, currency, text
variables.requiredWhether the send must supply this variable. Omitting a required value returns 422 on email, SMS, and WhatsApp sends. Always false when system is true, because you do not supply that slot's value.
variables.constraintA plain-language description of what values this variable accepts. When system is true it names where Bird takes the value from instead, because there is no value for you to send.
variables.sensitiveWhether this slot's value is redacted from stored message content. A placeholder replaces the sensitive value in message history; transport queues can still carry the text needed for delivery.
variables.systemWhether the value comes from Bird rather than from the send. Absent means false. Only email templates have system slots, identified by the reserved bird key or a dotted path beneath it; every SMS and WhatsApp slot is yours to fill. A draft can also name a reserved key no Bird value fills, including bird itself: constraint says so, and publishing that draft is rejected.
compatibility_severityThe 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 aproblem.warning: every finding is awarning.none: there are no findings.
Possible values: problem, warning, none
compatibilityWhat the previewed HTML uses that mail clients remove, ignore, or render inconsistently, in the order the patterns appear. Empty when nothing is worth reporting. Line and column count in the content.html you supplied, or in the template's own HTML when you supplied none, so they address the source rather than the rendered output. Previewing a published version is the exception: where the stored version keeps no authored copy of a language the publish step rewrote, the positions count in that rewritten body, which no response returns. A preview renders either way. 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.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.