Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Preview a broadcast for a contact

POST
/v1/email/broadcasts/{broadcast_id}/preview
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);
Odpowiedź200
{
  "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"
    }
  ]
}

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.

Parametry

broadcast_idstring

Broadcast identifier.

Treść żądania

template
nullable object

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

Pokaż parametry podrzędne
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.

Pokaż parametry podrzędne
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.

Treść odpowiedzi

resolution
object
wymagane

The published template version and language a validation or preview checked. It does not fix the version a later send uses.

Pokaż atrybuty podrzędne
contact_id
string

The contact whose values personalized this preview. Absent when the request named none.

subject
string
wymagane

The rendered subject line.

preheader
string
wymagane

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
wymagane

The rendered HTML body. When preheader is not empty, it includes the hidden block that carries that text.

text
string
wymagane

The rendered plain-text body.

resolved_parameters
object
wymagane

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
wymagane

Problems with the broadcast's inputs found while rendering this preview.

Pokaż atrybuty podrzędne
problems.code
string
wymagane

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
wymagane

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
wymagane

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
wymagane

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.

Powiązane zasoby

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Uzyskaj brief wdrożeniowy