Sign inGet Started
Comenzar
Guías
Referencia de API
SDKs
CLI
Base de conocimientos
Registro de cambios

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);
Respuesta200
{
  "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.

Parámetros

broadcast_idstring

Broadcast identifier.

Cuerpo de la solicitud

template
nullable object

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

Mostrar parámetros secundarios
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.

Mostrar parámetros secundarios
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.

Carga de respuesta

resolution
object
obligatorio

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

Mostrar atributos secundarios
contact_id
string

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

subject
string
obligatorio

The rendered subject line.

preheader
string
obligatorio

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
obligatorio

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

text
string
obligatorio

The rendered plain-text body.

resolved_parameters
object
obligatorio

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
obligatorio

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

Mostrar atributos secundarios
problems.code
string
obligatorio

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
obligatorio

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
obligatorio

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
obligatorio

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.

Recursos relacionados

Continúa con la documentación, guías y ejemplos de este tema.

Obtener un resumen de implementación