Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Validate a broadcast

POST
/v1/email/broadcasts/{broadcast_id}/validate
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);
Response200
{
  "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"
    }
  ]
}

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.

Parameters

broadcast_idstring

Broadcast identifier.

Request Payload

template
nullable object

Replaces the template, language or parameters for this request. Null removes the template for this request.

Show child parameters
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.

Show child parameters
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 Payload

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.

Show child attributes
problems
array of object
required

The problems found. Empty when ready_for_admission is true.

Show child attributes
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

Continue with the documentation, guides and examples for this topic.

Get an implementation brief