--- title: "Get an email template preview" method: POST path: "/v1/email/templates/{template_ref}/preview" tags: ["email-templates"] --- # Get an email template preview `POST /v1/email/templates/{template_ref}/preview` ## Request - Base URL: `https://us1.platform.bird.com` - URL: `https://us1.platform.bird.com/v1/email/templates/{template_ref}/preview` - Auth: one of: - HTTP bearer - API key in cookie `bird_session` 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. ## Headers - `Idempotency-Key` string - `X-Workspace-Id` string - `X-Organization-Id` string ## Request body - EmailTemplatePreviewRequest: Sample values and options for rendering a template preview. Omit the body entirely to preview the current draft: `bird.contact.` tokens then fill from stand-in values, and a parameter you give no value for renders as empty. - `content` EmailTemplatePreviewContent: Unsaved email template content. Preview renders these fields instead of a stored draft; input analysis identifies their references without rendering. - `subject` string: The subject line, including any template expressions. - `preview_text` string: Inbox preview text. Preview and publication fold it into the top of the HTML as a hidden preheader. Input analysis includes its references. - `html` string: The HTML body, including any template expressions. - `text` string: The plain-text body. When omitted, a plain-text alternative is derived from the HTML for preview, input analysis, and publication. - `parameters` object: Sample 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. - `contact` string - `language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`. - `version` string ## Response `200` The rendered preview. - EmailTemplatePreview: A rendered preview of an email template: its subject, HTML, and plain-text bodies with the supplied sample values filled in, ready to display. - `editor_url` string, uri: Optional 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`. - `subject` string, nullable, required: The rendered subject line. Null when the template has no subject. - `html` string, nullable, required: The rendered HTML body. Null when the template has no HTML body. - `text` string, nullable, required: The rendered plain-text body. Derived from the HTML when the template has no separate plain-text body, and null when it has neither. - `language` string, required: A language tag in BCP-47 form, for example `en` or `pt-BR`. - `variables` TemplateVariable[], required: Every 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. - `key` string, required: The 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. - `type` string, required: The 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. - `required` boolean, required: Whether 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. - `constraint` string, required: A 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. - `sensitive` boolean: Whether 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. - `system` boolean: Whether 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_severity` 'problem' | 'warning' | 'none', 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. - `compatibility` EmailCompatibilityFinding[], required: What 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. - `rule_id` string, required: Which rule produced a finding. - `html_script`: a `