---
title: "Broadcasts"
url: /interfaces/broadcasts
---

# Broadcasts

> One message to contacts and Customers who consented: approved, sent in each reader's timezone, unsubscribed in one click, and posted to a feed agents read.

A broadcast is one message to an audience the file names, sent only to people who consented, and posted to a feed agents read.

```mermaid title="A broadcast, from draft to sent"
stateDiagram-v2
  [*] --> draft: Broadcast.create
  draft --> approved: the review Role
  approved --> scheduled: a time
  scheduled --> sending: the time comes
  sending --> sent: every copy out
  scheduled --> cancelled: cancelled
```

Seen: sending, sent. Private, a step inside the run: draft, approved, scheduled, cancelled.

## Broadcast or transactional
A message that delivers what a Customer bought, or answers its call, is a [transactional](/interfaces/channels.md) send. Anything else to many people is a broadcast.

| The message | It is | So it |
| --- | --- | --- |
| A receipt, a renewal notice, an edition a member paid for | Transactional | Goes to each entitled reader, with no unsubscribe from what was bought |
| A price change, a sunset, a security notice | Transactional, by law or by the [terms](/commerce/agreements.md#prices) | Reaches every [Customer](/reference/platform.md#customer) it affects, whatever its choices |
| News of the product, an offer, a launch | A broadcast | Reaches only contacts and Customers who consented, each copy with its unsubscribe |

## Each copy, and the feed
A copy is `queued`, `sent`, then `delivered` or `bounced`; a delivered copy may become `opened`, `unsubscribed` or `complained`.

Sending runs in each reader's timezone and [locale](/interfaces/locales.md). A send that would pass the plan's contacts or the [spend cap](/trust/account.md#holds) waits, and nothing is cut short.

With `feed`, each sent broadcast also posts to the product's news page and its JSON feed. A Customer's agent reads it there, or through a Watch on `Broadcast.sent`, and never needs an inbox.

## Audiences and consent
An audience is a list of plans and arrival routes. A plan name reaches its paying Customers; `customers` reaches all of them.

`interest`, `forms` and `preorders` reach [contacts](/interfaces/leads.md) by how each arrived. Every audience is filtered at send time by [consent](/interfaces/channels.md) and by [suppression](/interfaces/channels.md), never by a list you upload.

Each copy carries a one-click unsubscribe in its headers and its footer. An unsubscribe or a complaint suppresses the address within the minute, across every broadcast.

## One announcement
The weekly brief tells members and its interest list about a new Issue type, approved by an editor and posted to its feed.

```ts title="definition.ts"
import { define, generative } from 'apis.dev'

/** A weekly brief on the software companies that changed headcount, for members and their agents. */
export default define({
  name: 'briefs', domain: 'briefs.apis.dev',
  sources: {
    firms: { api: 'companyfacts.apis.dev', cost: { 'Company.search': 0.005 } },
  },
  Issue: {
    week: 'string!#', title: 'string', body: 'markdown',
    status: {
      draft:   { run: generative('This week in {firms}: who hired, who shrank') },
      review:  { in: 'drafted', role: 'editor' },
      publish: { in: 'reviewed', role: 'editor' },
      send:    { in: 'published', to: 'Member' },
    },
  },
  on: { 'every Mon 06:00': 'Issue.draft', 'Issue.published': 'Issue.send' },
  offer: {
    'Issue.list': 0, 'Issue.read': 0.25,
    Member: { month: 8, includes: { 'Issue.read': 'all' } },
  },
  broadcasts: {
    from: 'news',                                         // news@ on the product's Host
    audiences: { members: ['Member'], everyone: ['customers', 'interest'] },
    review: 'editor',
    feed: true,
  },
})
```

Your team reads each send with `Broadcast.get` on the [Operator plane](/trust/planes.md).

```http title="Response"
HTTP/1.1 200 OK
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_d14a7c0e93b2f6851a2c

{
  "id": "bc_4",
  "subject": "Hiring signals, now daily",
  "audience": "everyone",
  "state": "sent",
  "approvedBy": "editor",
  "reached": 1840,
  "filtered": { "noConsent": 212, "suppressed": 31 },
  "delivered": 1822,
  "bounced": 18,
  "complained": 1,
  "unsubscribed": 9,
  "feed": "https://briefs.apis.dev/news/bc_4"
}
```