> ## 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`, the default import of the v7 Node SDK. 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.
> 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.

export const Endpoint = ({method, path, name, href, children, bare}) => {
  const verb = String(method || "").toUpperCase();
  const title = verb + " " + path;
  const label = children || name || path;
  if (bare) {
    return href ? <a href={href}><code>{title}</code></a> : <code>{title}</code>;
  }
  if (!href) {
    return <span className="cx-endpoint" data-method={verb} title={title}>
        <span className="cx-endpoint-label">{label}</span>
        <span className="cx-endpoint-method">{verb}</span>
      </span>;
  }
  return <a className="cx-endpoint" data-method={verb} href={href} title={title}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">{verb}</span>
    </a>;
};

export const Doc = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="doc" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">DOC</span>
    </a>;
};

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 <Doc href="/docs/design/templates/overview">Template</Doc> is written, addressed to a <Doc href="/docs/recipients/lists-and-audiences/overview">list or audience</Doc>.

## Which one to use

Broadcasts and <Doc href="/docs/journeys/overview">journeys</Doc> 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 <Doc href="/docs/monitor/broadcast-performance">performance metrics</Doc>.

Each broadcast sends on a **single channel**. To reach the same group elsewhere, create a separate broadcast. Recipients are a <Doc href="/docs/recipients/lists-and-audiences/lists">list</Doc> you curate by hand, or an <Doc href="/docs/recipients/lists-and-audiences/audiences">audience</Doc> Courier keeps current from rules.

### Its content

You write a broadcast's content in the same editor a <Doc href="/docs/design/templates/overview">Template</Doc> uses, and it is stored as the same <Doc href="/docs/design/elemental/overview">Elemental</Doc> document. Variables resolve from each recipient's profile, so one broadcast reads differently for every person.

## Limits & behavior

* **Console or API.** Build a broadcast in the console, or drive the whole flow through the <Endpoint method="POST" path="/broadcasts" name="Create Broadcast" href="/docs/api-reference/broadcasts/create-broadcast">Broadcasts API</Endpoint>: create, write content, then send or schedule.
* **One channel per broadcast.** A broadcast cannot span channels. Make one per channel.
* **Content locks when scheduled.** To edit a scheduled broadcast, cancel it, edit, and reschedule.

## FAQ

<AccordionGroup>
  <Accordion title="Is there an API to send a Broadcast?">
    <Endpoint method="POST" path="/broadcasts" name="Create Broadcast" href="/docs/api-reference/broadcasts/create-broadcast" /> creates one, <Endpoint method="PUT" path="/broadcasts/{broadcastId}/content" name="Update Broadcast content" href="/docs/api-reference/broadcasts/update-broadcast-content" /> writes the content, and <Endpoint method="POST" path="/broadcasts/{broadcastId}/send" name="Send Broadcast" href="/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 <Doc href="/docs/send/overview">Send API</Doc>.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can a Broadcast use more than one channel?">
    Each broadcast uses one channel. Create a separate broadcast to reach the same group elsewhere.
  </Accordion>
</AccordionGroup>