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

# Send a broadcast

`POST /v1/broadcasts`

## Request

- Base URL: `https://api.sendora.se`
- URL: `https://api.sendora.se/v1/broadcasts`
- Auth: HTTP bearer

Stores the content once and one message per entry of `messages`, up to 50,000, on a broadcast stream, in one transaction. Each message is a message in the log with its own events and webhooks, sent with the recipient’s own unsubscribe link where `{{ unsubscribe_url }}` stands. Each message may carry `substitutions`, up to 20 strings that replace `{{ key }}` in the subject, the text and the HTML, escaped in the HTML; a key the content names must be given by every message. Addresses on the stream’s suppression list are dropped and counted; a list with nothing left, a missing placeholder, a missing substitution, a transactional or archived stream and a count over the monthly cap are refused whole. The Idempotency-Key is required: a retry under the same key answers the same broadcast.

## Headers

- `idempotency-key` string, required

## Request body

- object
  - `streamId` string, uuid, required: The broadcast stream of this server the messages go on.
  - `from` union, required: The sender. Its domain must be a verified sending domain of the server.
    - string, email
    - object
      - `email` string, email, required
      - `name` string, nullable: A display name of up to 200 characters.
  - `subject` string, required: The subject line.
  - `text` string: The plain-text part, with {{ unsubscribe_url }} where the link goes. At least one of text and html is required.
  - `html` string: The HTML part, with {{ unsubscribe_url }} where the link goes.
  - `headers` object: Custom headers on every message, at most 20. The List-Unsubscribe pair is Sendora’s too. Sendora writes these itself, so a message may not set them: From, Sender, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Return-Path, Received, Delivered-To, DKIM-Signature, DomainKey-Signature, Authentication-Results, Received-SPF, and any name that starts with Content-, Resent-, ARC- or X-Kumo.
  - `attachments` object[]: At most 20, sent with every message. A message with its attachments encoded may be at most 10 MB.
    - `name` string, required
    - `content` string, byte, required
    - `contentType` string
    - `contentId` string, nullable
  - `tag` string, nullable: A label of up to 100 characters, returned with the message and its events.
  - `metadata` object: Up to 20 key-value pairs of your own, on the broadcast and on every message.
  - `messages` object[], required: One entry per message, at most 50000; a larger list is several broadcasts under one tag.
    - `to` union[], required: Recipients of this message; at most 50 across to, cc and bcc.
      - union: An address as a plain string, or an object with the address and a display name.
        - string, email
        - object
          - `email` string, email, required
          - `name` string, nullable: A display name of up to 200 characters.
    - `cc` union[]: Copied recipients, shown in the message.
      - union: An address as a plain string, or an object with the address and a display name.
        - string, email
        - object
          - `email` string, email, required
          - `name` string, nullable: A display name of up to 200 characters.
    - `bcc` union[]: Blind-copied recipients.
      - union: An address as a plain string, or an object with the address and a display name.
        - string, email
        - object
          - `email` string, email, required
          - `name` string, nullable: A display name of up to 200 characters.
    - `metadata` object: Up to 20 key-value pairs for this message, merged over the broadcast's.
    - `headers` object: Custom headers for this message, merged over the broadcast's.
    - `substitutions` object: Up to 20 strings that replace {{ key }} in the subject, the text and the HTML of this message; a key the content names must be given.

## Response `200`

The broadcast was stored; Sendora sends its messages from here.

- object: The broadcast was stored; Sendora sends its messages from here.
  - `broadcastId` string, uuid, required: The id the messages, the progress and the cancel refer to.
  - `status` 'accepted', required
  - `total` integer, required: Messages stored; each is a message in the log.
  - `suppressed` integer, required: Addresses dropped for standing on the stream’s suppression list.
  - `submittedAt` string, date-time, required
  - `test` boolean, required: True when the server is a test server: the messages go through everything but delivery, and nobody receives them.

## Other responses

- `400`: The body, the query or a header does not match what the route takes, or the Idempotency-Key header is missing.
- `401`: The key is missing, malformed or revoked.
- `402`: The account's first payment has not arrived or an unpaid charge has stopped live sending, or the send's price would take what the account owes for emails past its limit.
- `403`: The key is of the other kind, the account is paused, closed or not yet approved for a live server's sends, or a connected app may not do this here.
- `413`: The body exceeds 10 MB.
- `422`: The broadcast cannot be sent as it stands; the code says why.
- `429`: The monthly cap of the account, the server or the test servers is used up.
- `503`: Sending is disabled for everyone for the moment; retry after the seconds in Retry-After.

---

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