Create a broadcast
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.
bearerAuthAuthorizationBearer <token>A secret API key from the dashboard: coss_live_… for production environments, coss_test_… for sandbox environments.
Idempotency-Key?stringMakes 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.
1 <= length <= 256Coss-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.
"2026-10-10"application/json- body
- body
- …
name*stringShown only to you.
1 <= length <= 200audience_id?stringSend to this audience…
segment_id?string…or to this segment (one of the two).
topic?stringThe 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.
^[A-Za-z0-9_-]{1,256}$from*stringreply_to?array<string>Addresses replies go to.
items <= 10subject*stringMay use {{{contact.<key>|fallback}}} (e.g. {{{contact.first_name|there}}}).
1 <= length <= 998preview_text?stringThe inbox preview line (a hidden preheader at the start of the HTML).
length <= 500html?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.
length <= 1000000text?stringThe plain text part. Takes the same placeholders as html.
length <= 1000000tracking?Which opens and clicks are tracked.
rate_per_second?integerRecipients per second, at most the plan's marketing rate (the default).
1 <= value <= 1000send?booleanStart sending right away.
scheduled_at?stringStart sending at this time (ISO 8601 with an offset, at most 30 days ahead).
date-timeThe new broadcast.
application/json- response
- response
- …
object*"broadcast""broadcast"id*stringname*stringShown only to you.
status*stringdraft (editable), scheduled, sending, paused (see pause_reason), sent, canceled, or failed (see error).
"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*stringWho it's sent from.
reply_to*array<string>Addresses replies go to.
subject*stringThe 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.
date-timestarted_at*|When sending started. null: it hasn't.
date-timecompleted_at*|When it finished. null: it hasn't.
date-timecanceled_at*|When it was canceled. null: it wasn't.
date-timerecipients_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*stringdate-timeupdated_at*stringdate-timeimport { 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"}