---
title: "Send a rendered broadcast test"
method: POST
path: "/v1/email/broadcasts/{broadcast_id}/test"
tags: ["email-broadcasts"]
---

# Send a rendered broadcast test

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

## Request

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

Supply the same changes, contact and fingerprint as a new preview to send the exact rendered content to an authorized current organization member with workspace access. Requires template read and emails write permission. Alternate-member and machine destinations also require members read. A change to template content, envelope fields, parameters or contact values returns E04089 (BroadcastPreviewChanged), a conflict_error. This does not send the campaign audience. A confirmed response replays unchanged for the same key and request within the configured idempotency window, with fresh authorization and member access checks. A replay sends no other test.

## Path parameters

- `broadcast_id` string, required

## Headers

- `Idempotency-Key` string, required
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- EmailBroadcastTestRequest: The inputs of a preview, repeated with its fingerprint, and the member to send its rendered content to. Send the same template, envelope and contact fields the preview used; nothing is saved to the broadcast. A user may send to their own current member email; another destination, or a machine principal, also requires members read permission. The personalization contact and the destination are independent.
  - `template` EmailBroadcastTemplateUpdate: A change to the template, language, or parameter maps a broadcast sends. Omitted properties retain their values unless the template ID changes. A changed ID clears the old language, parameters and parameter overrides before applying supplied replacements; repeating the same ID retains them.
    - `id` string
    - `language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `parameters` EmailBroadcastParameters: 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.
    - `parameter_overrides` EmailBroadcastParameterOverrides: 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` union: A sender or recipient address. Accepts a plain email string (`jane@acme.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@acme.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request. Responses always return the object form.
    - string: Email address, optionally in RFC 5322 mailbox form with an embedded display name.
    - EmailAddress: An email address with an optional display name.
      - `email` string, email, required: Email address.
      - `name` string: Display name shown alongside the address in mail clients.
  - `reply_to` EmailAddressInput[], nullable: Replaces the reply-to addresses for this request. Null removes them.
    - union: A sender or recipient address. Accepts a plain email string (`jane@acme.com`), an RFC 5322 mailbox string with an embedded display name (`Jane Doe <jane@acme.com>`), or an object carrying the address and an optional display name. All forms can be mixed freely within one request. Responses always return the object form.
      - string: Email address, optionally in RFC 5322 mailbox form with an embedded display name.
      - EmailAddress: An email address with an optional display name.
        - `email` string, email, required: Email address.
        - `name` string: Display name shown alongside the address in mail clients.
  - `headers` EmailBroadcastHeaders: Custom email headers as name and value pairs. Up to 25 of them, each value up to 998 characters.
  - `contact_id` string
  - `to` string, email, required: The email address of a current organization member with access to this workspace.
  - `preview_fingerprint` string, required: The `preview_fingerprint` returned by the preview whose content you are sending.

## Response `202`

Test email accepted.

- EmailBroadcastTestResult: An email message, including a recipient's copy of a broadcast. `broadcast_id` identifies the broadcast that sent the message and is absent for other sends. A broadcast records one message per recipient; these copies share the same `broadcast_id`.
  - `id` string, required
  - `from` EmailAddress, required: An email address with an optional display name.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `to` EmailAddress[], required: Primary recipients. Length is the recipient count. Use the broadcasts endpoint for audience-targeted sends. Each entry's `name` is present when a display name was provided on the send.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `cc` EmailAddress[]: CC recipients.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `bcc` EmailAddress[]: BCC recipients.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `subject` string, required: The subject line as delivered. For a send that used a template, the stored subject is the template's, so this reports it with the send's `parameters` substituted in, which is what the recipient saw.
  - `category` 'marketing' | 'transactional', required: Content classification, which controls suppression policy: - `marketing`: Blocks on all suppression reasons. - `transactional`: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail.
  - `reply_to` EmailAddress[], nullable: Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `status` 'scheduled' | 'accepted' | 'processed' | 'deferred' | 'delivered' | 'partial_failure' | 'bounced' | 'complained' | 'rejected' | 'canceled', required: Aggregate delivery status of an email, derived from its recipients' states. In flight: - `scheduled`: The message is queued to send at a future time and has not been dispatched yet. - `accepted`: The initial status of an immediate send. The message is queued for its recipients. - `processed`: Delivery is underway, so at least one recipient's message is on its way out and none has failed. - `deferred`: At least one recipient's mailbox provider asked for a retry, and delivery attempts continue. Final: - `delivered`: Every recipient's mail server accepted the message. - `bounced`: Every recipient permanently failed (bounced or was rejected). - `rejected`: Every recipient was rejected before a delivery attempt (for example, all recipients were suppressed). - `partial_failure`: Some recipients permanently failed while others were delivered or are still in flight. - `canceled`: A scheduled message was canceled before it was sent. `complained` takes precedence over every other status: at least one recipient reported the message as spam, regardless of what happened to the rest.
  - `accepted_count` integer, required: How many recipients are in the `accepted` state, meaning we have the message and are getting ready to deliver it.
  - `processed_count` integer, required: How many recipients the message has been prepared for and queued for delivery.
  - `delivered_count` integer, required: How many recipients' messages were accepted by their mail server.
  - `bounced_count` integer, required: Number of recipients that resulted in a permanent delivery failure.
  - `complained_count` integer, required: Number of recipients that reported spam.
  - `deferred_count` integer, required: Number of recipients in transient delivery deferral. Their mail server asked for a retry, and delivery attempts continue.
  - `rejected_count` integer, required: Number of recipients rejected before delivery. Read the per-recipient `rejection_reason` field on `GET /v1/email/messages/{message_id}/recipients` for the specific cause.
  - `processing_latency_ms` integer, nullable: Time between the send being accepted and the message being prepared for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches `processed`.
  - `delivery_latency_ms` integer, nullable: Time between the message being processed and the receiving mail server accepting it, in milliseconds, for the fastest delivered recipient. Null until the first recipient is delivered.
  - `total_latency_ms` integer, nullable: End-to-end accept → delivered time for the fastest delivered recipient, in milliseconds. Null until the first recipient is delivered.
  - `open_count` integer, required: Total open events across all recipients.
  - `click_count` integer, required: Total click events across all recipients.
  - `requested_language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
  - `resolved_language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
  - `template_id` string
  - `template_version_id` string
  - `broadcast_id` string
  - `tags` Tag[]: Labels on this message, each one a `name` and a `value`, that you can filter and search messages by. Use tags for anything you want to find messages by later, and `metadata` for data you only want handed back to you.
    - `name` string, required: Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
    - `value` string, required: Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
  - `metadata` object: Any JSON you kept on the message. We store it and hand it back in webhook payloads, and that is all it does. If you want to search or filter by it, use `tags` instead.
  - `parameters` object, nullable: The substitution values this send supplied, whether inline or from a template, or null if none were supplied. They are the values applied to `subject` and to the bodies the content endpoint returns, kept so you can see what produced the delivered copy and not only the result.
  - `attachments` EmailAttachmentRef[]: Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed. When content storage is enabled, download an attachment by its `id` via the message's attachment endpoint.
    - `id` string
    - `filename` string, required: Filename as shown to the recipient.
    - `content_type` string: Resolved MIME type at send time.
    - `size` integer, required: Decoded size in bytes.
    - `inline` boolean: True when the attachment was sent inline via a `content_id` reference in the HTML body, false for regular file attachments.
    - `content_id` string, nullable: The Content-ID set at send time, when the attachment was inline.
  - `track_opens` boolean, required: Whether open tracking is enabled for this send.
  - `track_clicks` boolean, required: Whether click tracking is enabled for this send.
  - `created_at` string, date-time, required: When the send request was accepted.
  - `thread_id` string, nullable: Thread this message belongs to, or null when the message is not part of one.
  - `in_reply_to_message_id` string
  - `delivered_at` string, date-time, nullable: When all recipients reached a terminal delivered state, or null if not yet fully delivered.
  - `scheduled_at` string, date-time: When this message is scheduled to send, for a send created with a future send time. Absent for an immediate send. Stays set after the scheduled send fires.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Insufficient balance
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)