> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send to an Audience

> Send a published campaign to a stored recipient list, now or on a schedule, with idempotent retries 📨

## Endpoint

```json theme={null}
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](https://docs.connectly.ai/audiences/overview) you stored earlier. This is the endpoint that supports scheduling.

<Tip>
  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.
</Tip>

## 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](#retrying-safely).                                                                                                      |
| `onInvalidEntries` | string | No       | `reject_all` (default) or `skip`. See [Unusable recipients](#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. |

```json theme={null}
{
  "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

```json theme={null}
{
  "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](#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.

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

***

## Get sendout status

```json theme={null}
GET https://api.connectly.ai/v1/businesses/{businessId}/get/sendouts/{sendoutId}
```

```json theme={null}
{
  "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](https://docs.connectly.ai/campaigns/send-campaigns) reports synchronously. Covers scheduled, sending, and completed. |
| `error`      | The send will not go out. See `error`.                                                                                                                                                      |

<Note>
  This endpoint reports whether the send was accepted, not whether the messages arrived. Delivery is reported by [webhooks](https://docs.connectly.ai/webhooks/overview).
</Note>

## 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.                                                                                                               |