Create a broadcast

POST
/v1/broadcasts

Creates a draft, or with send or scheduled_at a broadcast that starts sending (so it needs broadcast:send too). A broadcast goes to every contact of its audience or segment who is subscribed, reached by its topic and not suppressed, as one email each, at the plan's marketing rate.

Authorization

bearerAuth
headerAuthorizationBearer <token>

A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.

Header Parameters

Idempotency-Key?string

Makes retries safe: a repeated request with the same key and body returns the broadcast created first instead of creating another, for 24 hours. 1-256 characters.

Length1 <= length <= 256
Coss-Version?"2026-10-10"

The API version (a date) to use for this request. Defaults to your organization's version, pinned to the latest one when it first used the API and upgraded from the dashboard. The SDK always sends the version it was built for.

Value in"2026-10-10"

Request Body

application/json
  1. body
name*string

Shown only to you.

Length1 <= length <= 200
audience_id?string

Send to this audience…

segment_id?string

…or to this segment (one of the two).

topic?string

The topic the broadcast is about (its key): only contacts it reaches get it, and its unsubscribe link leaves just that topic. It is the emails' category.

Match^[A-Za-z0-9_-]{1,256}$
from*string
reply_to?array<string>

Addresses replies go to.

Itemsitems <= 10
subject*string

May use {{{contact.<key>|fallback}}} (e.g. {{{contact.first_name|there}}}).

Length1 <= length <= 998
preview_text?string

The inbox preview line (a hidden preheader at the start of the HTML).

Lengthlength <= 500
html?string

{{{contact.<key>|fallback}}} for contact fields and properties (escaped), and {{{unsubscribe_url}}}, {{{preferences_url}}}, {{{mailing_address}}}; a footer with the postal address and an unsubscribe link is added unless they are there.

Lengthlength <= 1000000
text?string

The plain text part. Takes the same placeholders as html.

Lengthlength <= 1000000
tracking?

Which opens and clicks are tracked.

rate_per_second?integer

Recipients per second, at most the plan's marketing rate (the default).

Range1 <= value <= 1000
send?boolean

Start sending right away.

scheduled_at?string

Start sending at this time (ISO 8601 with an offset, at most 30 days ahead).

Formatdate-time

Response Body

The new broadcast.

application/json
  1. response
object*"broadcast"
Value in"broadcast"
id*string
name*string

Shown only to you.

status*string

draft (editable), scheduled, sending, paused (see pause_reason), sent, canceled, or failed (see error).

Value in"draft""scheduled""sending""paused""sent""canceled""failed"
audience_id*|

The audience it goes to. null: a segment.

segment_id*|

The segment it goes to. null: an audience.

topic*|

The topic it's about (its key), and its emails' category. null: none.

from*string

Who it's sent from.

reply_to*array<string>

Addresses replies go to.

subject*string

The subject, before contact fields are filled in.

preview_text*|

The inbox preview line. null: none.

html*|

The HTML part, before contact fields are filled in. null: text only.

text*|

The plain text part. null: HTML only.

tracking*

Which opens and clicks are tracked.

rate_per_second*|

Recipients per second. null: the plan's marketing rate.

scheduled_at*|

When it's set to start. null: not scheduled.

Formatdate-time
started_at*|

When sending started. null: it hasn't.

Formatdate-time
completed_at*|

When it finished. null: it hasn't.

Formatdate-time
canceled_at*|

When it was canceled. null: it wasn't.

Formatdate-time
recipients_estimated*|

How many contacts it would reach, counted when it started.

pause_reason*|

Why a paused broadcast waits: paused (by you), billing_hold, budget_exceeded, usage_limit, marketing_paused, account_suspended, sending_paused.

error*|

Why it failed, such as target_unavailable when its audience, segment or topic was deleted while sending. null: it didn't.

stats*

How its emails fared so far.

created_at*string
Formatdate-time
updated_at*string
Formatdate-time
import { Coss } from "coss";const coss = new Coss({  apiKey: process.env.COSS_API_KEY,  baseUrl: "https://api.coss.com",});const { data, error } = await coss.email.broadcasts.create({  name: "October newsletter",  segment_id: "seg_01k7c8m4q2f3e9v6t5r1n0p8yz",  topic: "newsletter",  from: "Acme <news@acme.com>",  subject: "What's new, {{{contact.first_name|there}}}",  html: "<p>Hi {{{contact.first_name|there}}},</p><p>…</p><p><a href=\"{{{unsubscribe_url}}}\">Unsubscribe</a></p>",  scheduled_at: "2026-10-20T09:00:00Z",});
{  "object": "broadcast",  "id": "bcast_01k7c8m4q2f3e9v6t5r1n0p8yz",  "name": "October newsletter",  "status": "sent",  "audience_id": null,  "segment_id": "seg_01k7c8m4q2f3e9v6t5r1n0p8yz",  "topic": "newsletter",  "from": "Acme <news@acme.com>",  "reply_to": [],  "subject": "What's new, {{{contact.first_name|there}}}",  "preview_text": null,  "html": "<p>Hi {{{contact.first_name|there}}},</p>",  "text": null,  "tracking": {    "opens": true,    "clicks": true  },  "rate_per_second": null,  "scheduled_at": "2026-10-20T09:00:00.000Z",  "started_at": "2026-10-20T09:00:01.000Z",  "completed_at": "2026-10-20T09:12:40.000Z",  "canceled_at": null,  "recipients_estimated": 1200,  "pause_reason": null,  "error": null,  "stats": {    "recipients": 1200,    "sent": 1200,    "delivered": 1180,    "bounced": 6,    "complained": 1,    "failed": 0,    "opened": 540,    "clicked": 120,    "unsubscribed": 4  },  "created_at": "2026-10-15T12:00:00.000Z",  "updated_at": "2026-10-20T09:12:40.000Z"}