---
title: "Create a broadcast"
method: POST
path: "/broadcasts"
tags: ["Broadcasts"]
---

# Create a broadcast

`POST /broadcasts`

## Request

- Base URL: `https://api.mepmail.dev`
- URL: `https://api.mepmail.dev/broadcasts`
- Auth: HTTP bearer

Creates a broadcast to a segment, and schedules it when send is true.

## Request body

- CreateBroadcastRequest
  - `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 verified for the team
  - `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` union: Reply-To address or list
    - string
    - string[]
  - `preview_text` string: Inbox preview (preheader) text
  - `topic_id` string, uuid, nullable: 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"

## Response `200`

Broadcast created (and scheduled when send: true)

- SendBroadcastResponse
  - `id` string, uuid, required
  - `finishes_at` string, nullable: When the last email is expected to go out (ISO 8601); null when unknown
  - `estimated` true: finishes_at is an estimate that moves as other sends come in
  - `warning` object
    - `code` 'paced' | 'queued_behind', required: paced: more than the capacity available now; queued_behind: other sends go first
    - `days` integer, required: Days the send spans
    - `message` string, required

## Other responses

- `400`: Broadcast state conflict
- `401`: Missing, malformed or invalid API key
- `403`: Restricted API key or sending paused
- `404`: Not found
- `422`: Validation error
- `429`: Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After

---

[API](https://skmtc.dev/mepmail/apis/mepmail-api.md) · [All operations](https://skmtc.dev/mepmail/apis/mepmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mepmail/apis/mepmail-api/revisions/262a89f73730?raw)