Broadcasts

A broadcast sends one email to a whole audience: a newsletter, an announcement, or any single piece of content that goes out to many recipients at once. We resolve the audience's members into the recipient list when the send starts, so a broadcast reaches whoever is a member of the audience at that moment.

Create broadcasts in Email > Broadcasts in the dashboard, through the broadcasts API, with bird email broadcasts, or through the MCP server. The TypeScript, Python, Go and PHP SDKs carry a broadcasts resource for the whole lifecycle: draft one, change it while it is still a draft, send it now or at a later time, list the workspace's broadcasts, read one with its counters, cancel one that is scheduled or sending, delete one still in draft, and read its recipients, events, clicked links, the send allowance a send would draw on, and the audience counts a send resolves against. For a one-off recipient list, use batch sending or single sends.

Build a draft

Start from the Broadcasts list with New broadcast. The composer is a single page: an audience and sender bar at the top, the email content below it, and a settings control for category, tracking, and tags. There is no separate save step. Every change autosaves once the broadcast has an audience and a sender, so a draft exists as soon as those two are set, and sending it later is a separate, explicit action.

Use the To field to pick an audience, or select New to create one without leaving the composer.

Open the settings control in the composer header for three more things:

• The open and click tracking switches.
• Up to 20 tags, each a name and a value, to filter this broadcast by later.
• The category, which defaults to marketing.

The From address

A broadcast sends from an address on a verified sending domain. Pair a local part with one of your verified domains, and add a display name if you want one. Add a Reply-To address if you want replies routed elsewhere. Selecting Review warns you if the domain is not verified.

The template

A broadcast points at one of your workspace's email templates, and the template has the subject line and the body the broadcast sends. Each recipient's contact properties fill in the template's variables when the send runs, so one broadcast personalizes its content per recipient. A broadcast can only fill in contact properties, so a template variable naming anything else is refused when you send, and the error names the variable.

Write the content directly in the canvas below the subject line, or select Choose a template to start from an existing one. That option is only available while the broadcast is blank, since picking a template once you have written a subject or a body would overwrite it. A broadcast sends the template's published version, so a template that only has a draft cannot back a send.

A template that has more than one language sends one of them to the whole audience. Name it as template.language when you create or update the broadcast, and leave it out to send the template's default language. Changing only the language keeps the broadcast on the version it is fixed to, once it has one. A broadcast is fixed to a version when it is prepared for sending, so a scheduled broadcast sends the version that is published at that moment, whether or not you change its language before then.

Send or schedule

Coming soon: Waiting for funds and resume controls described below are not yet available. A broadcast that runs out of funds currently fails with quota_exceeded. Use Get a broadcast to check failure_detail and add funds if it identifies a balance shortfall. A top-up does not restart a failed broadcast; review which recipients were not sent to before creating another send. A message accepted for delivery but still deferred is already sent; exclude that recipient from the new broadcast.

Sending is a separate, explicit action, available from the composer's Review button or from the broadcast's detail page through Send or reschedule. Each opens a dialog that checks the broadcast is complete, warns you about anything likely to make the send fail, then lets you choose Send now or pick a time up to a year ahead. A scheduled broadcast stays editable, and you can reschedule it right up until sending actually starts.

Sending checks that the audience still has someone to reach. An audience where nobody has an email address, or where every address is suppressed, is refused at that point instead of failing later.

Two organization-level limits are checked when you send.

The first is how many broadcasts you can send in a billing period, when your plan sets a number. Saved drafts do not count toward it, and canceling a broadcast does not give the allowance back. Once you have used it up, you either wait for the next billing period or move to a plan with a higher limit.

The second limits concurrent broadcasts. If you select Send now while the limit is reached, the request is rejected. A scheduled broadcast waits for a free slot.

Before sending, review the estimated cost for the recipients who can receive the broadcast and any allowance warning in the Send dialog. Members with billing access also see the wallet balance and whether automatic top-up is on. The cost includes tax when a price is available; prices and usage can change before sending. If your plan has no broadcast estimate, the dialog says so rather than showing a zero cost. The allowance is an estimate shared with other email sends. Scheduling a broadcast does not reserve its balance, and another broadcast can use funds before this one finishes.

If automatic top-up is enabled, your existing settings may charge your saved payment method more than once as the broadcast sends. Starting a broadcast does not increase your top-up amount or authorize a separate payment for the whole audience.

If the balance runs out, the broadcast shows Waiting for funds for up to 20 minutes, whether automatic top-up is enabled or not. It checks for funds once a minute. Adding funds manually or through automatic top-up can restart sending during this window. A top-up that leaves your account blocked for insufficient funds does not restart sending. Partial top-ups do not extend the current wait. Once sending has continued, a later interruption starts a new 20-minute wait.

If the wait ends before sending can continue, the broadcast becomes Paused and your organization's billing contacts receive an email. Check the balance and add funds if needed. Waiting broadcasts keep their concurrent sending slot; paused broadcasts release it.

Open the broadcast and select Resume broadcast. Check that its dates, offers, and deadlines are still valid: the remaining recipients will receive the message later than intended.

In the Resume broadcast dialog, expand Preview email to review a saved workspace template. Previewing requires email_management:read; ask an authorized teammate to review it if you lack that permission. Built-in templates and missing saved content cannot be previewed here. If the preview is unavailable, follow the template checks below and leave the broadcast paused unless you can verify what remaining recipients will receive. The preview is optional and does not block resuming.

For a broadcast started at least 24 hours ago, the confirmation includes its age in hours and a warning about late delivery. Adding funds does not automatically resume a paused broadcast.

To review the message before resuming through the API, get the broadcast and read its started_at and pinned template references. Get the template using template.id; scope: system identifies a built-in template. If the template read returns 404, try its pinned version by ID because published workspace versions remain readable after deletion. For a workspace template, get that template version with template.id as template_ref and template.version_id as version_id. Review the subject and body in template.language, or the version's default_language if no language was selected. Reading this content requires email_management:read; ask an authorized teammate to review it if you lack that permission. Built-in lookups show current catalogue content. Broadcasts with frozen content keep it, but older broadcasts can read the catalogue again when resumed. Neither a current lookup nor an earlier message alone proves what remaining recipients will receive. Leave the broadcast paused unless you can verify that content.

The resume API and SDKs require confirm: true for a broadcast that old. With the CLI, review the broadcast first, then pass --yes to bird email broadcasts resume to acknowledge late delivery. The CLI returns a warning without that flag and does not prompt interactively. The MCP resume tool uses confirm: true too; ask the person requesting the send to confirm that the message is still timely.

Programmatic callers can always pass confirm: true, including before the 24-hour threshold, if their application has already decided to continue delivery. This does not skip balance, sending allowance, permission, or concurrent-broadcast checks.

Resume keeps the saved template references and recipient list. Recipients already sent to are not sent the message again. Current suppressions and consent preferences apply according to the broadcast category: marketing unsubscribes do not block transactional broadcasts. It does not use another broadcast from your monthly allowance. Your account must no longer be blocked for insufficient funds, its sending allowance must cover the next batch, and a concurrent sending slot must be available. If a daily or monthly sending limit still blocks the batch, resume returns 429 and keeps the broadcast paused. Retry the same broadcast after the allowance resets or its limit changes. A currently suspended workspace returns 403 with E08024. After reactivation, a broadcast authorized before the suspension still cannot resume: the API returns 403 with E04102. Cancel that broadcast instead of retrying. Do not resend to the full audience without excluding recipients already sent to. Resuming does not reserve funds or guarantee that the remaining messages can all be sent. If the balance runs out after an explicit resume, a new 20-minute wait begins. You can cancel the broadcast instead if its message is no longer useful.

Find a broadcast

Search the list by tag or template name, or filter it by status, audience, or a date range. The date range filters on when each broadcast was created, not when it sent, so a broadcast you scheduled last week for a send next month still shows up under "Last 7 days."

Export the current view as a CSV from the button above the table, or call Export broadcasts as CSV, which takes the same filters. Above 50,000 rows, the export is refused rather than quietly cut short. Narrow the filters and try again.

Broadcast status

Coming soon: The waiting_for_funds and paused statuses below are not available yet. A broadcast that runs out of funds currently fails and does not resume after a top-up.

A broadcast's stage appears in the Status filter:

Each row's badge shows the exact status within its stage. That same value is what the API's status field returns.

Cancel or delete

Cancel a scheduled, sending, waiting, or paused broadcast from its detail page, with bird email broadcasts cancel, or with Cancel a broadcast and the broadcasts.cancel SDK method. Recipients it has not reached yet are skipped, and any message already on its way cannot be recalled. Delete only works on a draft and it is permanent, through the same three routes: the detail page, bird email broadcasts delete, or Delete a broadcast.

When a broadcast fails

The dashboard explains the failure and what to check next. For quota_exceeded, it shows the recorded reason and guidance about sending limits and funds. You can also use Get a broadcast and read failure_reason and failure_detail.

A broadcast's sending setup is checked only when the send starts. If the sending domain was verified at scheduling but lost verification before sending, the broadcast fails at that point. Verify the domain and send the broadcast again.

Broadcasts and single sends share the organization's email allowance. Adding funds does not restart a failed broadcast. Check which recipients were not sent to before creating another broadcast. Exclude recipients whose messages were accepted for delivery, including messages still deferred by the receiving server. The waiting and pause behavior is coming soon. Hard sending limits and payment restrictions still apply. Plans and pricing covers what each plan includes.

Track delivery

Once sending starts, the broadcast's Overview tab shows its recipient and sent counts, then its delivery, open, click, bounce, and complaint rates with their counts. The Recipients tab lists every recipient along with its delivery status, the reason if it did not deliver, when it was delivered, and its opens and clicks. Its search box requires a complete, valid email address; a partial address or a domain fails validation, marks the box invalid, and leaves the table showing whatever it showed before. A button above the table exports the tab as a CSV, and Export a broadcast's recipients as CSV returns the same file to an API key; either is capped at 500,000 rows with the same refuse-rather-than-truncate behavior as the broadcasts list export. The Events tab is the broadcast's raw event feed, using the event types described in events and webhooks.

Rehearse a broadcast

Put a sandbox address in the audience and that contact is simulated instead of sent to: delivered@messagebird.dev reports delivered, bounce@messagebird.dev bounces, and each produces the same events and webhooks a real recipient would. This is how you exercise a campaign, and the handler reading its events, without mailing anyone. An audience can mix sandbox and real contacts; every contact gets its own outcome. A simulated recipient still counts against your send allowance, so the rehearsal covers the same quota the real send would.

Next steps

• Audiences: the recipient lists a broadcast sends to
• Email templates: the subject and body a broadcast points at
• Email metrics: the workspace-wide view broadcasts feed into
• bird email broadcasts: one CLI command per broadcast operation
• Create a broadcast: the API reference, with full request and response schemas and a code sample per SDK
• Email broadcasts: one email to your whole audience: a video that sends a broadcast and reads its results