Broadcasts API

A broadcast sends one message, through the project's connector, to a segment of the project's members.

A broadcast sends one message, through the project's connector, to a segment of the project's members. It is a send, not a stored record: there is no index endpoint and no broadcast id, because nothing is persisted. What happened is reported by the broadcast.queued and broadcast.completed webhook events, which carry the audience and the delivery tallies.

A broadcast cannot be recalled. Every recipient is a real person and the message arrives in their private chat. Size the audience with the preview endpoint before you send; a segment that silently resolves to everyone is the one mistake this API cannot undo.

There is no separate read ability: knowing who a broadcast would reach is the same privilege as being able to reach them, so all three endpoints take broadcast:send.

Endpoints

GET/v1/projects/{project}/broadcasts/audiencesList every audience GET/v1/projects/{project}/broadcasts/previewPreview an audience POST/v1/projects/{project}/broadcastsSend a broadcast

List every audience

GET

All thirteen segments with labels, descriptions and current counts, so a UI can offer them without hard-coding the list. Segments that address a single window report recipient_estimate: null; they cannot be sized without a window id.

Field	Type	Meaning
`value`	string	The segment key to send as `audience`.
`label`, `description`	string	The words the dashboard shows, in the creator's language.
`requires_pass_window`	boolean	Whether the segment needs a `pass_window_id`.
`supports_plan_filter`	boolean	Whether `plan_id` is accepted. False for `lead` and the pass segments.
`requires_expiring_within_days`	boolean	Whether the segment reads a horizon. True only for `expiring_soon`.
`recipient_estimate`	integer or null	Who the segment reaches right now; null where a window must be named first.

Requires ability

broadcast:send

The token must hold this ability, or the call is refused with 403.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Responses

200OKapplication/json

Every segment with its label, its rules and a recipient estimate where one can be given without a window.

data*array<unknown>

The items.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/broadcasts/audiences"

{  "data": [    {      "value": "customer",      "label": "Customers Only",      "description": "Members holding a paid subscription right now.",      "requires_pass_window": false,      "supports_plan_filter": true,      "requires_expiring_within_days": false,      "recipient_estimate": 128    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: unknown[];}

Preview an audience

GET

Sizes a broadcast without sending it. The dashboard shows this before the confirm button, and an API caller needs the same safety rail.

curl "https://api.subscriby.net/v1/projects/$PROJECT_ID/broadcasts/preview?audience=customer&plan_id=$PLAN_ID" \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN"

The preview accepts the same audience, pass_window_id, plan_id and expiring_within_days as the send, and applies them identically, segments, plan narrowing and recipient rules alike, so a preview and the send it precedes can never describe different audiences. The fields answer the same as the send's, minus status.

Requires ability

broadcast:send

The token must hold this ability, or the call is refused with 403.

MCP tool

preview_broadcast_audience

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Query Parameters

audience?string

The segment to size: all (the default), customer, trialing, lead, churned, expiring_soon, cancelled_still_active, paused, trialing_cardless, all_pass_holders, all_pass_holders_not_in_queue, pass_holders or pass_holders_not_in_queue. An unknown value is 422 with reason: unknown_audience and the supported list.

Default"all"

pass_window_id?string

The access window for pass_holders and pass_holders_not_in_queue; ignored by every other segment.

Formatuuid

plan_id?string

Narrow the segment to members whose subscription is on this plan. Refused for lead and the pass segments with reason: plan_filter_unsupported; a plan of another project is reason: unknown_plan.

Formatuuid

expiring_within_days?integer

The horizon expiring_soon counts within, 1 to 90; a value outside the range clamps. Defaults to 7. Read by no other segment.

Default7

Responses

200OKapplication/json

The recipient count and ETA for the segment as described.

data*

The response's payload.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

With error.context.reason of unknown_audience (the context also lists supported values), plan_filter_unsupported or unknown_plan.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/broadcasts/preview"

{  "data": {    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "audience": "customer",    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",    "expiring_within_days": null,    "recipient_estimate": 41,    "estimated_seconds": 2  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: Data;}export interface Data {  project_id: string;  audience: string;  plan_id: string | null;  expiring_within_days: number | null;  recipient_estimate: number;  estimated_seconds: number;}

Send a broadcast

POST

curl -X POST https://api.subscriby.net/v1/projects/$PROJECT_ID/broadcasts \  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{    "message": "<b>New drop is live</b>\nDoors open at 19:00 UTC.",    "audience": "customer"  }'

202, not 200: the send is queued and runs in the background at roughly 28 messages a second to stay inside the platform's rate limit. The response describes what was addressed, not what was delivered.

Audience segments

Segment	Who it addresses
`all`	Every member reachable on the project's connector, whatever their status.
`customer`	Members holding a paid subscription right now.
`trialing`	Members currently inside a free trial.
`lead`	Members who have used the project's bot but never subscribed.
`churned`	Members who were customers and are not any more.
`expiring_soon`	Members whose subscription genuinely lapses within `expiring_within_days`.
`cancelled_still_active`	Members who cancelled but have not run out yet: still reachable, still winnable.
`paused`	Members who paused their subscription rather than ending it.
`trialing_cardless`	Members trialing without a card on file, who will not convert on their own.
`all_pass_holders`	Everyone holding a valid pass for any upcoming window.
`all_pass_holders_not_in_queue`	Everyone who has not tapped their invite link, across every upcoming window.
`pass_holders`	Everyone holding a valid pass for one access window you choose (`pass_window_id`).
`pass_holders_not_in_queue`	Holders of one window you choose who have not tapped their invite link yet.

A member is a recipient only if they have a linked chat on that project's connector. Members with no chat, or whose chat belongs to a different installation, are excluded silently, which is why recipient_estimate is frequently well below a project's total membership.

An auto-renewing subscription is never expiring_soon. A subscription's ends_at is rewritten to the new period end on every renewal, so a date inside the horizon describes an auto-renewing member's next invoice rather than an expiry. Counting it would place every monthly subscriber in this segment once a month. A member is counted only when their access genuinely lapses: they have cancelled, or the plan is not recurring.

Narrowing a segment to a plan

plan_id composes with audience rather than replacing it:

Request	Who it addresses
`audience=customer` + `plan_id=<gold>`	People paying for Gold right now.
`audience=churned` + `plan_id=<gold>`	People who held Gold and left.
`audience=paused` + `plan_id=<gold>`	People whose paused plan is Gold.
`audience=expiring_soon` + `plan_id=<gold>`	Gold members lapsing inside the horizon.

The plan and the state describe the same subscription, so a member paying for Silver who once trialled Gold is not matched by the first row. churned is the deliberate exception in the other direction: the subscription proving they held the plan is the one that ended, so it is not required to be live.

A plan_id sent with lead or a pass segment is refused with 422 and reason: plan_filter_unsupported, not ignored. Silently dropping it would return a recipient count for a different audience than the request described, and a caller has no way to notice.

Message formatting

The body is reduced to the HTML subset the delivering connector accepts before sending; for the messaging connector that is , , , , , <ins>, <s>, <strike>, <del>, <a>, <code>, <pre>, <blockquote> and <tg-spoiler>. Anything else is stripped, not escaped: the platform rejects an entire message containing an unknown tag, so removing it is what keeps the message deliverable.

The 4,096-character limit is the platform's own. A longer body is refused here rather than being truncated per recipient.

Refusals

Every 422 is refused before anything is queued. The underlying job re-checks the same conditions and aborts silently, which is correct for a background job and wrong for an API caller, so the endpoint rejects them up front rather than returning 202 for a send that could never leave. A segment that resolves to zero recipients is the send action's own refusal, shared with the dashboard: it is not queued.

Requires ability

broadcast:send

The token must hold this ability, or the call is refused with 403.

Fires events

broadcast.queued broadcast.completed

Delivered to every endpoint subscribed to them once the change is made.

MCP tool

broadcast_message

Runs the same action from an agent, behind the same ability.

Idempotent

Idempotency-Key

Send the header on every call; the same key replays the original response for 24 hours.

Authorization

bearerToken

AuthorizationBearer <token>

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Header Parameters

Idempotency-Key*string

A key unique to this operation, such as a fresh UUID. The same key replays the original 2xx response for 24 hours (with Idempotent-Replay: true), so a retry after a timeout never repeats the write; the same key with a different body is refused with 409.

Formatuuid

Request body

JSONWhat the request carriesRequiredapplication/json

A message and the segment of the project's members it goes to.

message*string

The message body, 1 to 4,096 characters, in the HTML subset the delivering connector accepts. Unknown tags are stripped rather than escaped, because the platform rejects a whole message that holds one.

Length1 <= length <= 4096

audience?BroadcastAudience

The segment to address: all (the default), customer, trialing, lead, churned, expiring_soon, cancelled_still_active, paused, trialing_cardless, all_pass_holders, all_pass_holders_not_in_queue, pass_holders or pass_holders_not_in_queue.

Value in

"all"
"customer"
"trialing"
"lead"
"churned"
"expiring_soon"
"cancelled_still_active"
"paused"
"trialing_cardless"
"all_pass_holders"
"all_pass_holders_not_in_queue"
"pass_holders"
"pass_holders_not_in_queue"

pass_window_id?|

The access window for pass_holders and pass_holders_not_in_queue; required by those two, ignored by every other segment.

Formatuuid

plan_id?|

Narrow the segment to members whose subscription is on this plan; it composes with audience rather than replacing it. Refused, not ignored, for lead and the pass segments.

Formatuuid

expiring_within_days?|

The horizon expiring_soon counts within, 1 to 90; defaults to 7. Read by no other segment.

Range1 <= value <= 90

Responses

202Acceptedapplication/json

202 with the segment, the verified filters, the recipient count and the ETA.

data*

The response's payload.

400Bad requestIDEMPOTENCY_KEY_MISSINGapplication/json

Every write needs an Idempotency-Key header. Send a fresh UUID per distinct operation.

error*

The one envelope every failure uses.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

error*

The one envelope every failure uses.

409ConflictIDEMPOTENCY_KEY_REUSEDapplication/json

The key was already used in the last 24 hours with a different request body.

error*

The one envelope every failure uses.

422Validation failedVALIDATION_FAILEDapplication/json

The payload broke a rule, and error.fields maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with error.message saying why and no fields. On this endpoint: VALIDATION_FAILED: with error.context.reason of no_connected_bot (the project has no connector connected, so it has no way to deliver), missing_capability (a pass segment on a project whose plan no longer includes passes), pass_window_required (a single-window segment with no pass_window_id), unknown_audience (the context lists the supported values), plan_filter_unsupported (a plan_id with lead or a pass segment) or unknown_plan (the plan_id is not this project's); or with no reason when the segment holds nobody right now, in which case error.message says which.

error*

The one envelope every failure uses.

425Too earlyIDEMPOTENCY_REPLAY_IN_PROGRESSapplication/json

The first request with this key is still running; retry in a few seconds and the original response is replayed.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/broadcasts" \  -H "Idempotency-Key: 0199a4ae-6c02-7b5c-9f51-c5f0da5e2f12" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'

{  "data": {    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "audience": "customer",    "pass_window_id": null,    "plan_id": null,    "expiring_within_days": null,    "recipient_estimate": 128,    "estimated_seconds": 5,    "status": "queued"  }}

Type definitions

The shapes above as types, ready to paste into your client.

Request

export interface StoreBroadcastRequest {  message: string;  audience?: "all" | "customer" | "trialing" | "lead" | "churned" | "expiring_soon" | "cancelled_still_active" | "paused" | "trialing_cardless" | "all_pass_holders" | "all_pass_holders_not_in_queue" | "pass_holders" | "pass_holders_not_in_queue";  pass_window_id?: string | null;  plan_id?: string | null;  expiring_within_days?: number | null;}

Response

export interface Response {  data: Data;}export interface Data {  project_id: string;  audience: string;  pass_window_id: string | null;  plan_id: string | null;  expiring_within_days: number | null;  recipient_estimate: number;  estimated_seconds: number;  status: string;}

broadcast.* eventsReact to sends and their outcomes.BroadcastsThe same feature in the dashboard.ZapierAnd [n8n](https://docs.subscriby.net/integrations/n8n): send broadcasts without writing code.

Broadcasts API

EndpointsCopy Anchor Link

List every audienceCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Preview an audienceCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Send a broadcastCopy Anchor Link

Audience segments

Narrowing a segment to a plan

Message formatting

Refusals

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Header ParametersCopy Anchor Link

Request bodyCopy Anchor Link

ResponsesCopy Anchor Link

Related

On this page

Endpoints

List every audience

Authorization

Path Parameters

Responses

Preview an audience

Authorization

Path Parameters

Query Parameters

Responses

Send a broadcast

Authorization

Path Parameters

Header Parameters

Request body

Responses