Skip to main content

Broadcasts

A Broadcast is a one-time mass email sent to every subscribed member of an Audience. It carries its own approval state and budget guard, then fans delivery out across batched background jobs so a large recipient list never runs as a single long synchronous loop.

Scenario: A team drafts a product-update email to a 40,000-member audience. They request approval; an admin approves it. The broadcast checks the budget, splits recipients into chunks of 100, and dispatches a batch of jobs. Once every chunk settles, the broadcast rolls to a terminal status.

Broadcast lifecycle

  1. 1 Draft — create the broadcast with a name, subject, body, and target audience. Status draft.
  2. 2 Pending approval — request approval. The broadcast records requested_by and moves to pending_approval. Approval state lives on the broadcast itself rather than a shared ApprovalRequest.
  3. 3 Approved — an authorised user approves; the broadcast records approved_by / approved_at and is ready to send.
  4. 4 Sending → Sent / Failed — delivery fans out (see below). The broadcast settles to sent when at least one recipient was delivered, otherwise failed. It can also be cancelled before sending.

Recipient chunking & delivery

Delivery is orchestrated by SendBroadcastJob, which:

  1. Gates on budget via BroadcastBudgetGuard::assertCanSend() using the pending recipient count.
  2. Splits the pending BroadcastRecipient rows into chunks of 100 with chunkById.
  3. Dispatches a SendBroadcastChunkJob per chunk as a single job batch on the outbound queue — the per-recipient send loop lives in the chunk job, so no single job runs the whole audience.
  4. On batch finally, finalizes the broadcast to its terminal status based on how many recipients were actually sent.
Each recipient is tracked by a BroadcastRecipient row with its own status (pending → sent), so a retried chunk never double-sends to someone already delivered.

In the UI

  • Broadcasts lists every broadcast with its audience, status, and recipient count.
  • Create drafts a new broadcast against an audience.
  • The detail page shows recipient delivery progress and the approval trail.

MCP tools

Tool Description
broadcast_list List the team's broadcasts.
broadcast_get Fetch a broadcast with status and recipient count.
broadcast_create Draft a broadcast for an audience.
broadcast_request_approval Move a draft to pending approval.
broadcast_approve Approve a pending broadcast and queue delivery.
broadcast_cancel Cancel a broadcast before it sends.

Related concepts