Send to an Audience

Endpoint

POST https://api.connectly.ai/v1/businesses/{businessId}/send/audience_campaigns

Parameter	Location	Description
`businessId`	Path	Your Connectly business ID.
`X-API-Key`	Header	Your API key.

Sends a published campaign to an audience you stored earlier. This is the endpoint that supports scheduling.

The campaign must have been published at least once in the Connectly Flow Builder. The send is pinned to the currently published version, so editing the campaign afterwards does not change what this send delivers.

Request body

Field	Type	Required	Description
`audienceId`	string	Yes	The audience to send to.
`campaignId`	string	Yes	UUID of the campaign to send.
`scheduledAt`	string	No	ISO 8601 datetime to dispatch at. Omit to dispatch as soon as the recipients have been checked.
`idempotencyKey`	string	No	Strongly recommended. See Retrying safely.
`onInvalidEntries`	string	No	`reject_all` (default) or `skip`. See Unusable recipients.
`sender`	string	No	Business channel to send from — WA Phone Number ID, E.164 number, or another identifier the channel understands. Defaults to your default channel.
`bidMultiplier`	number	No	How much of the template’s stored bid to spend: `1.0` bids the stored amount, `1.15` bids 15% more. Range `0.1`–`10.0`. Applies only to bidded MARKETING templates.

{
  "audienceId": "01925f3a-7c41-7e2b-9a10-3f0c8d5b6e47",
  "campaignId": "cc7be491-e449-4288-aa9b-b89fb593cfbd",
  "scheduledAt": "2026-11-27T13:00:00Z",
  "idempotencyKey": "black-friday-2026-wave-1"
}

Response

{
  "data": {
    "sendoutId": "2303a627-0e5d-4930-b61d-97a212fe2727",
    "campaignId": "cc7be491-e449-4288-aa9b-b89fb593cfbd",
    "campaignName": "black_friday",
    "campaignVersion": "01a0c706-f29e-ce3f-2bee-b70bafb72efc",
    "status": "processing",
    "acceptedCount": 0,
    "rejectedCount": 0,
    "scheduledAt": null,
    "error": null,
    "validationReportUrl": ""
  }
}

The response returns as soon as the send is accepted. Checking the recipients against the campaign happens afterwards, which is why status starts as processing and the counts start at 0. Poll Get sendout status for the outcome.

Scheduling

Pass scheduledAt to dispatch later. Constraints:

No more than 30 minutes in the past — a time slightly behind now dispatches on the next sweep rather than being rejected.
No more than 3 years ahead.
Honoured to the minute; seconds are truncated.

Recipients are checked against the campaign immediately, not at the scheduled time, so a list that would be rejected fails while you are still watching rather than silently at midnight.

Unusable recipients

onInvalidEntries decides what a recipient the campaign cannot accept — a missing required variable, for instance — does to the send.

Value	Behaviour
`reject_all`	Default. The send fails and nothing goes out, so you can fix the audience and send again.
`skip`	Dispatches the recipients that passed and reports the rest in `rejectedCount`.

When recipients are rejected, validationReportUrl on the status response links to an annotated copy of your CSV naming the offending rows.

Retrying safely

A send goes to a whole audience, so a retry after a timeout is expensive to get wrong. Mint an idempotencyKey and reuse it when retrying:

The same key returns the original response instead of creating a second send.
The same key with different parameters is rejected with 400 — that is a mistake, not a retry.
A key whose first request is still running returns 409. Retry once it finishes.
Keys are remembered for 24 hours, maximum 128 characters.

Without an idempotency key, a retry after a timeout sends to the entire audience twice.

Get sendout status

GET https://api.connectly.ai/v1/businesses/{businessId}/get/sendouts/{sendoutId}

{
  "data": {
    "sendoutId": "2303a627-0e5d-4930-b61d-97a212fe2727",
    "campaignId": "cc7be491-e449-4288-aa9b-b89fb593cfbd",
    "campaignName": "black_friday",
    "campaignVersion": "01a0c706-f29e-ce3f-2bee-b70bafb72efc",
    "status": "created",
    "acceptedCount": 9998,
    "rejectedCount": 2,
    "scheduledAt": "2026-11-27T13:00:00Z",
    "error": null,
    "validationReportUrl": "https://..."
  }
}

Status	Meaning
`processing`	The recipients are still being checked. Counts are `0`.
`created`	The send was accepted and exists — the same milestone Send Campaigns reports synchronously. Covers scheduled, sending, and completed.
`error`	The send will not go out. See `error`.

This endpoint reports whether the send was accepted, not whether the messages arrived. Delivery is reported by webhooks.

Errors

Status	Cause
`400`	`audienceId` or `campaignId` missing or malformed, `scheduledAt` outside the allowed window, or `idempotencyKey` reused for a different send.
`404`	The audience or campaign names nothing you own.
`409`	A request with the same `idempotencyKey` is still in flight.
`412`	The campaign has never been published, or its most recent send was stopped for a reason that would repeat.
`429`	More than 10 sends in a minute.

Get Started

Campaigns

Audiences

Messaging

Opt-Outs

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Webchat

Resources

Send to an Audience

Endpoint

Request body

Response

Scheduling

Unusable recipients

Retrying safely

Get sendout status

Errors

​Endpoint

​Request body

​Response

​Scheduling

​Unusable recipients

​Retrying safely

​Get sendout status

​Errors

Endpoint

Request body

Response

Scheduling

Unusable recipients

Retrying safely

Get sendout status

Errors