---
title: "Preview a broadcast for a contact"
method: POST
path: "/v1/email/broadcasts/{broadcast_id}/preview"
tags: ["email-broadcasts"]
---

# Preview a broadcast for a contact

`POST /v1/email/broadcasts/{broadcast_id}/preview`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/broadcasts/{broadcast_id}/preview`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Render the template's published content using the saved broadcast, the changes supplied in this request and contact values the caller can read. Supplied fields replace the saved values for this preview only. Requires template read permission. Supply contact_id when the template uses contact data. The preview's unsubscribe link does not unsubscribe a contact. This does not send mail. Each call renders a fresh result. An Idempotency-Key header is accepted but does not replay an earlier preview.

## Path parameters

- `broadcast_id` string, required

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EmailBroadcastPreviewRequest: Replacements over the saved broadcast, and the contact to render this preview for. A supplied field replaces the saved value for this preview only and an omitted field keeps it; nothing is saved. A changed template ID clears the saved language and parameters before supplied replacements apply, and repeating the same ID keeps them.
  - `template` EmailBroadcastTemplateUpdate: A change to the template, language, or parameter maps a broadcast sends. Omitted properties retain their values unless the template ID changes. A changed ID clears the old language, parameters and parameter overrides before applying supplied replacements; repeating the same ID retains them.
    - `id` string
    - `language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `parameters` EmailBroadcastParameters: Complete template input map. Each value is a string, number, boolean or null and is used exactly as given, so text containing braces or code-like syntax is never evaluated. Objects and lists are not accepted. Use bird.contact.first_name in the template for contact data. Names must be bare input names outside the bird namespace. Omission retains the map unless the template ID changes, which clears it; an empty object clears it, and null is invalid. The compact map is limited to 16384 UTF-8 bytes and 128 names. Individual email parameters keep their own format.
    - `parameter_overrides` EmailBroadcastParameterOverrides: Complete map of per-language parameter values, keyed by a BCP-47 language tag of at most 35 characters such as `es` or `pt-BR`. Each language holds only the names whose value differs for that language; a name it leaves out uses the value in `parameters`, including later changes to it. A value that is present always applies, even when it is `""`, `0`, `false`, `null` or equal to the `parameters` value. To return a name to the `parameters` value, send the map without it. Sending this map, even as `{}`, applies language rules to the broadcast: `parameters` must hold every input the default language's content, sender name, reply-to or headers use, and an input only the selected language uses may come from that language's entry instead. A broadcast that never sends it keeps the selected-language rules. Values for the default language, or for a language the broadcast does not send, are kept but not used. Omission retains the map unless the template ID changes, which clears it; an empty object removes every override, null is invalid and a language with no names is removed. Tags are stored in canonical BCP-47 form, so two spellings of one tag are refused. The compact map is limited to 16384 UTF-8 bytes, and `parameters` and every language together are limited to 128 distinct names.
  - `from` union: A sender or recipient address. Accepts a plain email string (`jane@acme.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@acme.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request. Responses always return the object form.
    - string: Email address, optionally in RFC 5322 mailbox form with an embedded display name.
    - EmailAddress: An email address with an optional display name.
      - `email` string, email, required: Email address.
      - `name` string: Display name shown alongside the address in mail clients.
  - `reply_to` EmailAddressInput[], nullable: Replaces the reply-to addresses for this request. Null removes them.
    - union: A sender or recipient address. Accepts a plain email string (`jane@acme.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@acme.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request. Responses always return the object form.
      - string: Email address, optionally in RFC 5322 mailbox form with an embedded display name.
      - EmailAddress: An email address with an optional display name.
        - `email` string, email, required: Email address.
        - `name` string: Display name shown alongside the address in mail clients.
  - `headers` EmailBroadcastHeaders: Custom email headers as name and value pairs. Up to 25 of them, each value up to 998 characters.
  - `contact_id` string

## Response `200`

Rendered broadcast preview.

- EmailBroadcastPreviewResult: A broadcast rendered for one contact, with the inputs it used. Preview sends nothing, and its unsubscribe link is a placeholder that unsubscribes no one.
  - `resolution` EmailBroadcastResolution, required: The published template version and language a validation or preview checked. It does not fix the version a later send uses.
    - `template_id` string, required
    - `observed_version_id` string, required
    - `requested_language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `effective_language` string, required: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `requirements_fingerprint` string, required: An opaque value that changes when the checked version, its content or the inputs it uses change. Compare it with an earlier value to tell whether the requirements are still the same. Do not parse it.
    - `default_language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
  - `contact_id` string
  - `subject` string, required: The rendered subject line.
  - `preheader` string, required: The text of the hidden preview block that this render of `html` includes, which inbox clients can show beside the subject. It is empty when the template has no preview text, when the text renders empty, or when the rendered HTML does not include the block. A version published earlier can have preview text whose block its markup leaves out, escapes or removes; publishing the template again places the block. This value describes the rendered HTML and does not show how a provider or inbox displays it. Use it instead of reading the hidden block in `html`.
  - `html` string, required: The rendered HTML body. When `preheader` is not empty, it includes the hidden block that carries that text.
  - `text` string, required: The rendered plain-text body.
  - `resolved_parameters` EmailBroadcastResolvedParameters, required: The broadcast inputs this render used, by name, each with the string, number, boolean or null value it used. It holds the values taken from `template.parameters` or the selected language's `template.parameter_overrides` entry, and only for names the rendered content or envelope uses. Contact values are never included. A number keeps the digits it was supplied with.
  - `problems` EmailBroadcastParameterProblem[], required: Problems with the broadcast's inputs found while rendering this preview.
    - `code` string, required: What a broadcast input diagnostic found. - `parameter_json_invalid`: the request body or an input map is not valid JSON. - `parameter_map_invalid`: `template.parameters` or `template.parameter_overrides` is not a JSON object of input names. - `parameter_name_invalid`: an input name is not a bare name outside the `bird` namespace. - `parameter_value_unsupported`: an input value is an object or a list. Values must be a string, number, boolean or null. - `parameter_duplicate_key`: an input name, or two spellings of one language tag, appears twice. - `parameter_bytes_exceeded`: an input map is larger than 16384 UTF-8 bytes. - `parameter_names_exceeded`: `template.parameters` and every language together hold more than 128 distinct names. - `parameter_depth_exceeded`: an input value is nested too deeply. - `parameter_language_invalid`: a `template.parameter_overrides` key is not a valid BCP-47 language tag. - `parameter_required`: the template or envelope uses an input that has no value. - `sensitive_input_unsupported`: the template uses an input it marks sensitive, which a broadcast cannot supply. - `render_profile_unsupported`: the template uses a Liquid operation that rendering with broadcast inputs does not support. - `rendered_envelope_invalid`: the rendered subject, sender name, reply-to addresses or a header is not valid for an email, for example because it contains a line break. - `contact_property_unknown`: the template reads a contact property this workspace has not defined. - `template_unavailable`: the broadcast has no template, or its template no longer exists or has no published version. - `language_unavailable`: the published version has no content in the selected language. - `sender_unavailable`: the broadcast cannot send from its `from` address or IP pool. - `audience_unavailable`: the broadcast's audience cannot be used for this send. - `recipient_render_failed`: content could not be rendered for a recipient while the broadcast was sending. - `render_budget_exceeded`: rendering went over a limit, named by `budget` with its `limit`. - `transport_missing`: the saved content of a prepared broadcast is unavailable. Contact Bird support. - `transport_invalid`: the saved content of a prepared broadcast no longer matches what was prepared. Contact Bird support.
    - `phase` string, required: Where a broadcast input diagnostic was found. - `request`: in the inputs this request supplied, before the template was checked. - `validation`: while checking the inputs against the current published template, as validate, preview and send do. - `execution`: while the broadcast was being prepared or sent. This phase appears on `failure_parameters`.
    - `severity` string, required: How a broadcast input diagnostic affects sending. - `error`: the broadcast cannot send until the problem is fixed.
    - `pointer` string: A JSON pointer to the request or broadcast field the problem is about, such as `/template/parameters/first_name` or `/from`. Absent when the problem is not about one field.
    - `site` string: The part of the email where the input is used. - `subject`: the subject line. - `html`: the HTML body, including its inbox preview text. - `text`: the plain-text body. - `from_name`: the sender display name. - `reply_to`: the reply-to addresses. A custom header is reported as `header:` followed by the header name as the broadcast sets it, for example `header:X-Campaign`.
    - `budget` string: The rendering limit that was exceeded, such as `output_bytes` or `nesting`, when `code` is `render_budget_exceeded`. It is reported with `limit` on problems from sending a broadcast, in `failure_parameters`.
    - `limit` integer: The value of the limit named by `budget`.
    - `contact_id` string
  - `preview_fingerprint` string, required: An opaque value for this rendered content. It changes when the published version, an input, a contact value, a fallback or the envelope changes. To send this content as a test, repeat the same inputs with this value. Do not parse it.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)