email-broadcasts

Validate a broadcast

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.

post/v1/email/broadcasts/{broadcast_id}/validate

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/broadcasts/{broadcast_id}/validate
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

broadcast_idstring required
Example:eb_01krdgeqcxet5s7t44vh8rt9mg

Broadcast identifier.

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

headersEmailBroadcastHeaders

Custom email headers as name and value pairs. Up to 25 of them, each value up to 998 characters.

Example request

{
  "template": {
    "id": "emt_01krdgeqcxet5s7t44vh8rt9mg",
    "language": "pt-BR"
  },
  "from": "Jane Doe <jane@acme.com>",
  "reply_to": [
    "Jane Doe <jane@acme.com>"
  ],
  "headers": {
    "X-Campaign": "spring-launch"
  }
}

Response

Broadcast input validation result.

ready_for_admissionboolean 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.

unused_parametersstring[] 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_parametersstring[]

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_parametersstring[]

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.

Example response

{
  "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"
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.