---
title: "Validate a broadcast"
canonical: "https://bird.com/docs/api/reference/validate-email-broadcast"
---

# Validate a broadcast

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

Check the saved broadcast or the changes supplied in this request against the template's published content. This does not save changes, select a template version for sending or evaluate recipients. Requires template read permission in addition to broadcast read. Each call computes a fresh result. An Idempotency-Key header is accepted but does not replay an earlier result.

## Code samples

**TypeScript**

```ts
const params = {
  template: {
    parameters: {
      title: "Welcome",
      offer: "OCTOBER20",
      discount: 20,
      featured: false,
    },
  },
};
const result = await bird.broadcasts.validate(
  "eb_01krdgeqcxet5s7t44vh8rt9mg",
  params,
);
console.log(result.ready_for_admission, result.problems);
```

Examples: [TypeScript](/docs/api/reference/validate-email-broadcast.ts.md) · [Python](/docs/api/reference/validate-email-broadcast.py.md) · [Go](/docs/api/reference/validate-email-broadcast.go.md) · [PHP](/docs/api/reference/validate-email-broadcast.php.md) · [CLI](/docs/api/reference/validate-email-broadcast.cli.md) · [MCP](/docs/api/reference/validate-email-broadcast.mcp.md) · [cURL](/docs/api/reference/validate-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"
  },
  "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.

## Response body

- `ready_for_admission` (boolean, required): Whether the current template and supplied broadcast inputs pass validation, including checks that the sender and audience can be used. Sending also checks permissions, limits, the audience's recipients and their values, so `true` does not guarantee the broadcast sends.
- `resolution` (object): The published template version and language that were checked. Absent when no published template could be selected.
- `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.
- `problems` (array of object, required): The problems found. Empty when `ready_for_admission` is true.
- `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.
- `unused_parameters` (array of string, required): Names supplied in `template.parameters`, or in the selected language's `template.parameter_overrides` entry, that the selected content and envelope do not use. Rendering the selected content ignores them. With `template.parameter_overrides`, this can include a name in `base_parameters` that only the default language uses, and `template.parameters` must still hold its value.
- `base_parameters` (array of string): Input names `template.parameters` must hold, returned with `resolution`. Without `template.parameter_overrides` these are the inputs the selected language uses. With it they are every input the default language's content or the envelope uses, including names the selected language does not use.
- `override_parameters` (array of string): Input names only the selected language uses, returned with `resolution`. Each may come from that language's entry in `template.parameter_overrides` or from `template.parameters`. Always empty without `template.parameter_overrides`.

## 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)