---
search:
  tags:
    - Broadcasts
    - POST
seo:
  description: >-
    Create a broadcast. Reference for the POST /broadcasts endpoint in the
    BillionSend API.
sidebar:
  label: Create a broadcast
  badge: POST
title: Create a broadcast
type: openapi-operation
---
`POST /broadcasts`

**Request body** (`application/json`, required)

- `name` (string) — Internal name shown in the dashboard
- `segment_id` (string<uuid>) — Segment to send to; omitted means every contact of the team
- `from` (string, required) — Sender, "Name \<user@domain\>"; the domain must be one of the team's own verified domains when the broadcast is sent: sending from an address on the shared inbox domain answers 403
- `subject` (string, required) — Subject line; supports {{{FIRST\_NAME|there}}} merge fields
- `html` (string) — HTML body; include {{{UNSUBSCRIBE\_URL}}} for the opt-out link
- `text` (string) — Plain-text body; at least one of html/text is required
- `reply_to` (string | string[]) — Reply-To address or list
- `preview_text` (string) — Inbox preview (preheader) text
- `topic_id` (string<uuid> | null) — Topic id; only contacts subscribed to it receive the broadcast
- `send` (boolean) — true sends (or schedules) immediately instead of saving a draft
- `scheduled_at` (string) — Deliver later (requires send: true): ISO 8601 with offset or relative like "in 1 hour"

Request body example:

```json
{
  "name": "string",
  "segment_id": "0dbbf761-5b2d-4647-8bfa-2b714456749c",
  "from": "string",
  "subject": "string",
  "html": "string",
  "text": "string",
  "reply_to": "string",
  "preview_text": "string",
  "topic_id": "646807af-5da6-43aa-83d3-8ac1d15ab4e5",
  "send": true,
  "scheduled_at": "string"
}
```

**Responses**

- `200` — Broadcast created (and scheduled when send: true)
- `400` — Broadcast state conflict
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Restricted API key, sending paused, or a From on the shared inbox domain
- `404` — Not found
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "finishes_at": "string",
  "estimated": true,
  "warning": {
    "code": "paced",
    "days": 0,
    "message": "string"
  }
}
```
