coss.comdocs

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>
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
Lengthlength <= 1000000
tracking?
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
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*string|null
segment_id*string|null
topic*string|null
from*string
reply_to*array<string>
subject*string
preview_text*string|null
html*string|null
text*string|null
tracking*
rate_per_second*integer|null
scheduled_at*|
Formatdate-time
started_at*|
Formatdate-time
completed_at*|
Formatdate-time
canceled_at*|
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, usage_limit, marketing_paused, account_suspended, sending_paused.

error*|null
stats*
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"}