---
title: "Create a broadcast"
method: POST
path: "/v1/email/broadcasts"
tags: ["email-broadcasts"]
---

# Create a broadcast

`POST /v1/email/broadcasts`

## Request

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

Creates a broadcast for a stored audience. The default is an editable draft.
Set `send` to `true` to send now or at `scheduled_at`; `scheduled_at` without
`send` set to `true` returns `422`. Use
[Create an email message](/docs/api/reference/create-email-message) for a small,
explicit recipient list.

Contacts in the audience at send time become recipients after suppressions. Read
their states with
[List recipients of a broadcast](/docs/api/reference/list-email-broadcast-recipients).
With `send`, the request returns `422` if any of these are true:

- The sender domain is not verified.
- No audience is selected, or the selected audience no longer exists.
- The audience has no contact with an email address, or every contact is suppressed for the broadcast's category.
- No template is set, or the set template has no published version.
- The organization has used its broadcast allowance for the current billing period, or (for an immediate send) is already at its concurrent-broadcast limit; schedule the send instead to wait for a free slot.

If the audience is empty when a scheduled send starts, the broadcast becomes
`failed` with a readable reason instead of silently dropping it.

## Headers

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

## Request body

- EmailBroadcastCreateRequest: A broadcast sends one email to a whole audience. Every field here is optional, so you can create an empty draft and fill it in later. To actually send, a broadcast needs three things: a `from` address on a verified domain, an `audience_id`, and a `template`. Leave `send` false, which is the default, and you get a draft. Update it as often as you like, then send it when you are ready. Set `send` to true and the broadcast goes out as soon as it is created, or at `scheduled_at` if you set one.
  - `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.
  - `audience_id` string
  - `template` EmailBroadcastTemplateCreate: The template a new broadcast sends, and which of that template's languages goes out.
    - `id` string, required
    - `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.
  - `reply_to` EmailAddressInput[]: Where replies to this broadcast should go. Give each address as a plain address, as `Jane <jane@acme.com>` to include a display name, or as an object with an address and a name. You can list more than one.
    - 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.
  - `tags` Tag[]: Labels on this broadcast, each one a `name` and a `value`, up to 20 of them. You can filter the broadcast list by a tag, break your stats down by one, and read them back off webhook payloads. Use tags for anything you want to find broadcasts 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 want to keep on the broadcast. We store it, hand it back when you read the broadcast, and include it in webhook payloads, and you can break stats down by a path inside it such as `metadata.order_id`. It can be up to 2 KB once serialized.
  - `track_opens` boolean: Whether to track opens for this broadcast.
  - `track_clicks` boolean: Whether to track link clicks for this broadcast.
  - `ip_pool_id` string: The IP pool to send this broadcast from. Pass a pool ID, or `ipp_shared` to send through the shared pool on purpose. Leave it out and the broadcast uses your organization's default pool. A pool we do not recognize, or one with no IPs available to send from, is refused with a `422`.
  - `category` 'marketing' | 'transactional': What kind of email this is. A broadcast sets this itself rather than taking it from its template, and it decides two things: which suppressions apply, and whether we add an unsubscribe header. `marketing`, the default, is held back from every suppressed address and has the one-click unsubscribe headers. `transactional` still goes to addresses suppressed for a complaint or an unsubscribe, and has no unsubscribe header. Only use `transactional` for genuine operational mail such as a terms-of-service update or a service outage notice. Marketing content sent this way still reaches people who have already unsubscribed from you.
  - `send` boolean: Whether to send the broadcast as soon as it is created. Set it to true and the broadcast goes out immediately, or at `scheduled_at` if you set one. Leave it false, which is the default, and you get a draft you can update and send later.
  - `scheduled_at` string, date-time: When to send the broadcast. It has to be at least 30 seconds and at most 365 days from now. It requires `send` to be true, so a `scheduled_at` on its own is refused rather than saved on the draft.

## Response `201`

Draft broadcast created.

- EmailBroadcast
  - `id` string, required: Broadcast ID.
  - `display_label` string: Label for selecting this broadcast on list and single-broadcast reads. With `email_management` read access, uses the retained subject from the template version resolved when execution starts, then its non-generated name. Draft and scheduled broadcasts use the name. Omitted when no authoritative label is available; clients can show a localized Untitled broadcast fallback. Without that access, uses the canonical broadcast ID. Absent from mutation responses.
  - `from` 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.
  - `audience_id` string
  - `template` EmailBroadcastTemplate: The template a broadcast sends, the exact version of it the broadcast is fixed to, and which of that version's languages goes out. `parameters` and `parameter_overrides` are returned on customer detail and mutation responses when the caller has email_management read permission, and omitted without that permission and from list responses. They are also omitted from staff-only responses. Broadcasts created before parameters existed return `parameters` as an empty object. `parameter_overrides` is also omitted for a broadcast that has never sent it; an empty object means language rules apply with no overrides.
    - `id` string, required
    - `language` string: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `version_id` string
    - `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.
  - `html_bytes` integer: Size of the HTML body this broadcast sends, in bytes, or 0 when its content has no HTML part. Measured on the template version the broadcast sends, using the selected language. Recipient merge values can change its size. Returned on a single broadcast read, and absent from the list and from the broadcast that creating, updating, sending or canceling one returns, none of which measure the content. Absent too when the broadcast has no template or its content can no longer be read.
  - `text_bytes` integer: Size of the plain-text body this broadcast sends, in bytes, or 0 when its content has no plain-text part. Measured, and absent, the same way as `html_bytes`.
  - `category` 'marketing' | 'transactional', required: What kind of email this is, which decides how suppressions apply to it. A `marketing` broadcast is held back from every suppressed address. A `transactional` one still goes to addresses suppressed for a complaint or an unsubscribe, because those suppressions are about marketing mail.
  - `ip_pool_id` string: The IP pool this broadcast sends from, or `ipp_shared` when it sends through the shared pool. Absent when it sends on your organization's default pool.
  - `reply_to` EmailAddress[]: Where replies to this broadcast go, if you want them somewhere other than the `from` address. Absent when you have not set one.
    - `email` string, email, required: Email address.
    - `name` string: Display name shown alongside the address in mail clients.
  - `headers` object: Any custom email headers set on the broadcast. Returned on a single broadcast read and on the broadcast that creating, updating, sending or canceling one returns, and absent from the list. The unsubscribe headers we add ourselves are not included.
  - `status` 'draft' | 'scheduled' | 'accepted' | 'sending' | 'sent' | 'canceling' | 'canceled' | 'failed', required: Where the broadcast itself has got to. This is separate from what happened to individual recipients, which the broadcast's own `sent_count`, `delivered_count`, `bounced_count` and `complained_count` tell you. Those four are fields on the broadcast, not on everything that carries this status, and reading the broadcast's recipients or its events gives the same outcomes one recipient at a time. - `draft`: Created, and not sent or scheduled yet. - `scheduled`: Due to send at `scheduled_at`. You can still edit it, and you can still change the time, right up until sending starts. - `accepted`: Taken for immediate sending. Nothing has gone out yet. - `sending`: On its way. Some recipients have been sent to and some have not. - `sent`: Every recipient has been sent to. - `canceling`: A cancellation is under way and the remaining sends are stopping. - `canceled`: The cancellation finished. Anything already on its way to a recipient when you canceled cannot be pulled back. - `failed`: The broadcast could not be sent. Reading the broadcast gives `failure_reason`, which says why. If it had already started sending, the recipients it reached keep their delivery status and carry on producing events. A draft is deleted rather than canceled, because it was never sent.
  - `next` NextAction[]: What to do next about this broadcast, given the state it is in. Each entry names one action and says why it is worth taking. Present on reads that compute it: an empty list means there is nothing to do, and the field is absent entirely on responses that do not report next actions.
    - `kind` string, required: What you do about this step. - `operation`: call the operation named in `operation`, then read again. - `external`: act somewhere this API does not reach, then read again. - `wait`: nothing is asked of you, so read again later. - `terminal`: nothing you do resolves this, so stop retrying. Tolerate a value you do not recognize: show the `description` and offer no action.
    - `description` string, required: A short, human-readable label for the step, suitable for display.
    - `operation` string: The operationId to call. Present only when `kind` is `operation`. The operation's own schema says how to call it; this says only which one, and what to address it with.
    - `params` object: The parameters that address the operation, by name: `{"sender_id": "…"}` for an operation on `/v1/sms/senders/{sender_id}/requirements`. A parameter the operation takes in its query string is given the same way, so an operation addressed as `?subject_id=` carries `{"subject_id": "…"}`. Every parameter the call needs is here, whether its value came from the thing you were acting on or is fixed for this step, so you can make the call from this object alone. Present only when `kind` is `operation` and the operation names a subject. A request body, when the operation takes one, is described by the operation's own schema and never appears here.
    - `url` string, uri: A URL to open. Present only when `kind` is `external`, and only when the step has one. An external step whose `description` says to go and do something with no URL to open is normal.
  - `failure_reason` 'empty_audience' | 'audience_unavailable' | 'content_invalid' | 'insufficient_funds' | 'quota_exceeded' | 'internal_error' | 'null', nullable: Why the broadcast failed. Set when `status` is `failed`, and `null` the rest of the time. - `empty_audience`: There was nobody to send to. Either the audience has no members, or every address in it is suppressed. - `audience_unavailable`: The audience no longer exists, so there was nothing to resolve. - `content_invalid`: The broadcast could not be set up to send. `failure_detail` explains what went wrong. It is one of these: - The broadcast has no template, or the template it uses no longer exists. Choose an existing template and send the broadcast again. - The template has no published version, or its published version has no subject and no body. Publish the template, or add content and publish it. - The template uses a loop or reads a value that a broadcast cannot provide. Remove it, or use a contact property instead, then publish the template again. - The template requires a language, but the broadcast has not selected one. Set `template.language` to one of the template's languages and send the broadcast again. - The selected language is not available on the published template version. Choose one of that version's languages, or publish a version that includes the selected language. - The sending domain is no longer verified. Verify the domain again. - The configured IP pool has no usable IP address. - We could not hand the prepared message to the delivery system. This is a problem on our side. - `insufficient_funds`: There was not enough in the workspace balance to pay for the send. - `quota_exceeded`: The send would have gone past your organization's daily or monthly email allowance, whichever runs out first. This can happen when the broadcast is being prepared, or partway through sending if the remaining recipients no longer fit. `failure_detail` gives you the count and the limit. - `internal_error`: Something went wrong on our side. Retry, and open a support ticket if it keeps happening.
  - `failure_detail` string, nullable: A sentence explaining the failure in more detail than `failure_reason` does, and `null` when the broadcast has not failed. Show it to the person using your app. Do not write code that reads it, because the wording can change. Branch on `failure_reason` instead.
  - `recipient_count` integer, required: Number of recipients after suppressed addresses are removed from the audience. This is 0 until sending starts and the audience becomes a recipient list.
  - `sent_count` integer: How many recipients the broadcast has been sent to, counting every recipient whose status is `processed` or later. The number rises while the broadcast is `sending` and stops changing once the broadcast has finished. These counters are exact. The email stats endpoints report on the same sending but are approximate, so use these numbers when you need the precise count. Absent when the broadcast comes back from creating, updating, sending or canceling it, none of which read the counters. List and single-broadcast reads return 0 when no delivery events are recorded. When counters are unavailable, those reads still return 200 and omit the counters. Read the broadcast again for the numbers.
  - `delivered_count` integer: How many recipients' messages were accepted by their mail server. Absent when `sent_count` is.
  - `bounced_count` integer: How many recipients the message could not be delivered to at all. Absent when `sent_count` is.
  - `complained_count` integer: How many recipients marked the message as spam. Absent when `sent_count` is.
  - `open_count` integer: How many times the message was opened, added up across every recipient. One recipient opening it twice counts twice. Absent when `sent_count` is.
  - `click_count` integer: How many times a link in the message was clicked, added up across every recipient. One recipient clicking twice counts twice. Absent when `sent_count` is.
  - `sending_ips` string[]: The IP addresses this broadcast's messages went out from, up to 100 of them. A broadcast is spread across every address in its pool, so more than one can appear. The receiving mail systems name the address when they deliver, bounce or defer a message, so this stays absent until the first of those comes back. Returned on a single broadcast read, and absent from the list and from the broadcast that creating, updating, sending or canceling one returns, none of which read them. For delivery and latency broken down per address, read the sending-IP stats.
  - `unique_opens_non_prefetched` integer: How many distinct recipients opened the message at least once, excluding opens auto-fetched by inbox privacy features (such as Apple Mail Privacy Protection and the Gmail image proxy). A recipient who opened several times, or whose inbox prefetched the message, counts once. Absent when `sent_count` is.
  - `unique_clicks` integer: How many distinct recipients clicked a link in the message at least once. A recipient who clicked several times counts once. Absent when `sent_count` is.
  - `out_of_band_bounces` integer: How many recipients bounced after the message had already been accepted for delivery. A recipient who bounced this way more than once counts once. Absent when `sent_count` is.
  - `delivered_recipients` integer: How many distinct recipients a delivery landed for. This is the denominator to measure `unique_opens_non_prefetched`, `unique_clicks` and `complained_count` against. It differs from `delivered_count`, which reports how many recipients are currently in the delivered state: a recipient who was delivered to and then complained moves to `complained_count` and leaves `delivered_count`, but stays here, because the message did reach them. Absent when `sent_count` is.
  - `tags` Tag[]: Labels on this broadcast, each one a `name` and a `value`, that you can filter and search broadcasts by. Use tags for anything you want to find broadcasts 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 want to keep on the broadcast. 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.
  - `track_opens` boolean, required: Whether opens are tracked for this broadcast.
  - `track_clicks` boolean, required: Whether link clicks are tracked for this broadcast.
  - `created_at` string, date-time, required: When the broadcast was created.
  - `scheduled_at` string, date-time: When the broadcast is due to send, and absent when it is not scheduled.
  - `started_at` string, date-time: When the broadcast started sending. Absent until then. Compare with `sent_at`, which is when the broadcast finished sending.
  - `sent_at` string, date-time, nullable, required: When the last recipient was sent to and the broadcast became `sent`. Null until then. Compare with `started_at`, which is when the broadcast started sending.
  - `canceled_at` string, date-time: When the broadcast was canceled, and absent if it never was. This is when cancellation was requested, so it is set as soon as the status is `canceling` and does not move while the remaining sends stop and the status becomes `canceled`.
  - `failure_parameters` EmailBroadcastFailureParameters: Why a broadcast stopped because its template inputs could not be prepared or rendered. It names fields and contacts and never includes input or contact values.
    - `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.
    - `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`.
    - `pointer` string: A JSON pointer to the broadcast field the failure is about, such as `/template/parameters/first_name` or `/template`.
    - `observed_version_id` string
    - `problems` EmailBroadcastParameterProblem[]: Up to 20 of the problems found. A recipient problem names its contact in `contact_id`.
      - `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.
      - `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`.
      - `severity` string, required: How a broadcast input diagnostic affects sending. - `error`: the broadcast cannot send until the problem is fixed.
      - `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.
      - `site` string: The part of the email where the input is used. - `subject`: the subject line. - `html`: the HTML body, including its inbox preview text. - `text`: the plain-text body. - `from_name`: the sender display name. - `reply_to`: the reply-to addresses. A custom header is reported as `header:` followed by the header name as the broadcast sets it, for example `header:X-Campaign`.
      - `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`.
      - `limit` integer: The value of the limit named by `budget`.
      - `contact_id` string
    - `failure_count` integer, required: How many recipients failed to render, including those not listed in `problems`. It can be `0` when the broadcast failed while it was being prepared, before any recipient was rendered.

## Other responses

- `202`: Broadcast accepted for delivery.
- `400`: Bad request
- `401`: Authentication required
- `402`: Insufficient balance
- `403`: Insufficient permissions
- `404`: Resource not found
- `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)