> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Broadcasts

> Send one message to a whole list or audience, now or on a schedule. Each broadcast uses one channel and suits newsletters, launches, and policy updates.

A broadcast is one message to a whole list or audience, sent now or on a schedule.

You design the content once, pick who receives it, and send. Use a broadcast for one-off sends: newsletters, product launches, and policy updates.

A broadcast is those two things together: content written the way a [Template](https://www.courier.com/docs/design/templates/overview.md) is written, addressed to a [list or audience](https://www.courier.com/docs/recipients/lists-and-audiences/overview.md).

## Which one to use

Broadcasts and [journeys](https://www.courier.com/docs/journeys/overview.md) both send to many people, and the difference is what starts the send.

| | Broadcasts | Journeys |
| - | - | - |
| Shape | One message to a group | Per-user flow, single or multi-step |
| Trigger | You send it, now or scheduled | A user event or API call |
| Recipients | A list or an audience | Users entering the flow |
| Best for | Newsletters, promotions, announcements | Onboarding, receipts, digests, re-engagement |

Sending the same message to a group at a chosen moment is a broadcast. A user's action that should send a message or start a sequence is a journey.

## How it works

### From draft to sent

A broadcast moves through three states:

* **Draft**: created but not yet sent or scheduled.
* **Scheduled**: queued for a set time. You can reschedule or cancel, but the content is locked. To change the message, cancel, edit, and schedule again.
* **Sent**: delivered, with [performance metrics](https://www.courier.com/docs/monitor/analytics.md#broadcasts).

Each broadcast sends on a **single channel**. To reach the same group elsewhere, create a separate broadcast. Recipients are a [list](https://www.courier.com/docs/recipients/lists-and-audiences/lists.md) you curate by hand, or an [audience](https://www.courier.com/docs/recipients/lists-and-audiences/audiences.md) Courier keeps current from rules.

### Its content

You write a broadcast's content in the same editor a [Template](https://www.courier.com/docs/design/templates/overview.md) uses, and it is stored as the same [Elemental](https://www.courier.com/docs/design/elemental/overview.md) document. Variables resolve from each recipient's profile, so one broadcast reads differently for every person.

Build a broadcast in the console, or drive the whole flow through the [Broadcasts API](https://www.courier.com/docs/api-reference/broadcasts/create-broadcast.md): create, write content, then send or schedule.

## FAQ

> [accordion] Is there an API to send a Broadcast?
>
> [`POST /broadcasts`](https://www.courier.com/docs/api-reference/broadcasts/create-broadcast) creates one, [`PUT /broadcasts/{broadcastId}/content`](https://www.courier.com/docs/api-reference/broadcasts/update-broadcast-content) writes the content, and [`POST /broadcasts/{broadcastId}/send`](https://www.courier.com/docs/api-reference/broadcasts/send-broadcast) or `/schedule` delivers it. You can also skip Broadcasts and send to a `list_id` or `audience_id` through the [Send API](https://www.courier.com/docs/send/overview.md).

> [accordion] Should I send to a List or an Audience?
>
> Use a list for a group you curate by hand, and an audience for a rule-based segment Courier keeps current as profiles change. Either works as recipients.
