# Broadcasts

Send one email to an audience now, or schedule it.

A broadcast is one email to an [audience](https://sendocado.com/docs/audiences), sent now or at a time you choose: a product update, a newsletter issue, an announcement.

## Create a draft

```sh Create a broadcast
curl -X POST "https://sendocado.com/api/v1/projects/$PROJECT_ID/broadcasts" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "October product update",
  "filter_groups": [
    {
      "filters": [
        {
          "type": "tag",
          "op": "has",
          "tag": "customer"
        }
      ]
    }
  ],
  "subject": "What’s new in Acme this month",
  "preview_text": "Faster exports and a new dashboard.",
  "html": null,
  "markdown": "# What’s new\n\nHi {{ first_name | there }}, exports are now twice as fast.",
  "template_id": null
}'
```

## Send or schedule it

Sending and scheduling are status changes, made with an update that carries every field:

| From | To | What happens |
| --- | --- | --- |
| `draft` | `sending` | Sending starts within 15 seconds |
| `draft` | `scheduled` | Sent at `scheduled_for` (a time in the future, in milliseconds) |
| `scheduled` | `draft` | Unscheduled |
| `scheduled` | `sending` | Sent now instead |
| `sending` | `canceled` | No more emails are created; ones already queued still go |

When every contact has been reached, the status becomes `sent`. While `has_open_sends` is true, some of its emails still wait for the provider’s answer.

```sh Schedule a broadcast
curl -X PUT "https://sendocado.com/api/v1/broadcasts/$BROADCAST_ID" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "October product update",
  "filter_groups": [
    {
      "filters": [
        {
          "type": "tag",
          "op": "has",
          "tag": "customer"
        }
      ]
    }
  ],
  "subject": "What’s new in Acme this month",
  "preview_text": "Faster exports and a new dashboard.",
  "html": "<h1>What’s new</h1>\n<p>Hi {{ first_name | there }}, exports are now twice as fast.</p>\n",
  "markdown": null,
  "template_id": null,
  "status": "scheduled",
  "scheduled_for": 1790259200000
}'
```

Before scheduling or sending, the same checks as for a campaign run: content, a working sender, a verified domain and a postal address. The broadcast readiness route lists what is missing.

## Who gets it

Each contact gets a broadcast at most once. Unsubscribed and blocked addresses are skipped. If your plan’s monthly emails run out mid-send, sending stops there.

## Results

The broadcast’s sends are its recipients: list them with the [sends route](https://sendocado.com/docs/api/sends) and `broadcast_id`. Broadcast stats give totals, rates, a daily series and clicks per link.

See the [Broadcasts reference](https://sendocado.com/docs/api/broadcasts) for every route.