---
title: "Preview a broadcast for a contact"
canonical: "https://bird.com/docs/api/reference/preview-email-broadcast"
---

# Preview a broadcast for a contact

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

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.

## Code samples

**TypeScript**

```ts
const params = {
  template: {
    parameters: {
      title: "Welcome",
      offer: "OCTOBER20",
      discount: 20,
      featured: false,
    },
  },
  contact_id: "con_01krdgeqcxet5s7t44vh8rt9mg",
};
const preview = await bird.broadcasts.preview(
  "eb_01krdgeqcxet5s7t44vh8rt9mg",
  params,
);
console.log(preview.subject, preview.preview_fingerprint);
```

Examples: [TypeScript](/docs/api/reference/preview-email-broadcast.ts.md) · [Python](/docs/api/reference/preview-email-broadcast.py.md) · [Go](/docs/api/reference/preview-email-broadcast.go.md) · [PHP](/docs/api/reference/preview-email-broadcast.php.md) · [CLI](/docs/api/reference/preview-email-broadcast.cli.md) · [MCP](/docs/api/reference/preview-email-broadcast.mcp.md) · [cURL](/docs/api/reference/preview-email-broadcast.curl.md)

## Example response `200`

```json
{
  "resolution": {
    "template_id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
    "observed_version_id": "emv_01krdgeqcxet5s7t44vh8rt9mg",
    "requested_language": "pt-BR",
    "effective_language": "pt-BR",
    "default_language": "pt-BR"
  },
  "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "problems": [
    {
      "code": "parameter_required",
      "phase": "validation",
      "severity": "error",
      "pointer": "/template/parameters/first_name",
      "site": "subject",
      "budget": "output_bytes",
      "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg"
    }
  ]
}
```

## Path parameters

- `broadcast_id` (string): Broadcast identifier.

## Request body

- `template` (nullable object): Replaces the template, language or parameters for this request. Null removes the template for this request.
- `template.id` (string): Select this template. Changing the ID clears the old language, parameters and parameter overrides before supplied replacements. Repeating the same ID retains those values and clears the selected template version, so the next preparation uses the template's latest published version. Omit id to retain the selected template. Adding parameters to a draft created before parameters existed may clear its selected version so it uses the template's latest published version. To clear a draft's selection, set template itself to null.
- `template.language` (nullable string): The BCP-47 language tag that goes to the whole audience, such as `en` or `pt-BR`. It must be an exact match for a language on the template's published version, so `fr-CA` does not select `fr`. Leave it out to keep the language already selected. If you change the template `id` in the same request, the old language is cleared with the old template. Set this to `null` to use the published version's default language, unless the template has `language_source_required` set.
- `template.parameters` (object): 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.
- `template.parameter_overrides` (object): 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` (string or object): Replaces the sender for this request. Give it as a plain address, as `Jane <jane@acme.com>` to include a display name, or as an object with an address and a name.
  - Variant `Email string`: Email address, optionally in RFC 5322 mailbox form with an embedded display name.
  - Variant `object`: An email address with an optional display name.
    - `from.email` (string, required): Email address.
    - `from.name` (string): Display name shown alongside the address in mail clients.
- `reply_to` (nullable array): Replaces the reply-to addresses for this request. Null removes them.
- `headers` (object): Replaces the custom headers for this request rather than adding to them. Up to 25 of them, each value up to 998 characters. The header rules for updating a broadcast apply.
- `contact_id` (string): The workspace contact whose values fill `bird.contact.` inputs. Required when the template or envelope reads contact data. Present values are used as they are, and a property's fallback applies only when the contact has no value for it.

## Response body

- `resolution` (object, required): The published template version and language a validation or preview checked. It does not fix the version a later send uses.
- `resolution.template_id` (string, required): The template the broadcast uses.
- `resolution.observed_version_id` (string, required): The published template version that was checked.
- `resolution.requested_language` (string): The language selected in `template.language`, by the broadcast or this request. Absent when none is selected and the published version's default language is used.
- `resolution.effective_language` (string, required): The language whose content was checked.
- `resolution.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.
- `resolution.default_language` (string): The published version's default language. When the broadcast has `template.parameter_overrides`, `template.parameters` must hold every input this language's content and the broadcast's sender name, reply-to and headers use; without it the selected language's rules apply. Read the complete lists from `base_parameters` and `override_parameters` on the validation result. Template inputs describe template content only and do not include the sender name, reply-to or headers.
- `contact_id` (string): The contact whose values personalized this preview. Absent when the request named none.
- `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` (object, 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` (array of object, required): Problems with the broadcast's inputs found while rendering this preview.
- `problems.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.

  Possible values (may grow over time): `parameter_json_invalid`, `parameter_map_invalid`, `parameter_name_invalid`, `parameter_value_unsupported`, `parameter_duplicate_key`, `parameter_bytes_exceeded`, `parameter_names_exceeded`, `parameter_depth_exceeded`, `parameter_language_invalid`, `parameter_required`, `sensitive_input_unsupported`, `render_profile_unsupported`, `rendered_envelope_invalid`, `contact_property_unknown`, `template_unavailable`, `language_unavailable`, `sender_unavailable`, `audience_unavailable`, `recipient_render_failed`, `render_budget_exceeded`, `transport_missing`, `transport_invalid`
- `problems.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`.

  Possible values (may grow over time): `request`, `validation`, `execution`
- `problems.severity` (string, required)

  How a broadcast input diagnostic affects sending.

  - `error`: the broadcast cannot send until the problem is fixed.

  Possible values (may grow over time): `error`
- `problems.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.
- `problems.site` (string)

  Where in the email the input is used. Absent when the problem is not tied to one place.

  Possible values (may grow over time): `subject`, `html`, `text`, `from_name`, `reply_to`
- `problems.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`.
- `problems.limit` (integer): The value of the limit named by `budget`.
- `problems.contact_id` (string): The contact whose values were being rendered, when the problem came from one recipient.
- `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.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)