Skip to main content
An audience is a recipient list you upload once and reuse. Instead of putting every recipient in the body of each send, you store the list, get back an id, and send a published campaign to that id. This suits large lists and repeat sends. Send Campaigns carries its recipients inline, which is the right shape for a handful of entries; an audience is the right shape for tens of thousands, and it is the only way to schedule a send for later.

​
How it works

1

Upload the recipient CSV

Call Upload recipients with your CSV as multipart form data. You get back an asset id.
2

Store it as an audience

Call Create or replace an audience with that asset id. Connectly reads the file, canonicalizes every recipient, and stores the list under an audience id.
3

Send a campaign to it

Call Send to an audience with the audience id and a published campaign id. Send now, or pass scheduledAt to dispatch later.
4

Poll the send

Call Get sendout status to see whether the recipients passed the campaign’s checks. Delivery itself is reported by webhooks.

​
The CSV

One row per recipient, with a header row.
Column names must match the campaign’s variables exactly, including case. A campaign expecting name will reject every row of a file whose column is customername. Under the default onInvalidEntries: reject_all that fails the whole send, so check the names before a large send.
An audience holds at most 1,000,000 recipients. Files must be UTF-8.

​
Replacing an audience

Creating and replacing are the same call: pass audienceId to overwrite that audience’s recipients, or omit it to have one minted. Replacing is how an audience changes, so repeating the same request is harmless.
Sends already created from an audience are unaffected by a later replace. Each send keeps its own copy of the recipients as they stood when it was created.

​
Limits

An audience send creates and verifies a sendout, which costs far more than an inline send — hence the lower limit.

​
Endpoints

Upload recipients

POST /v1/businesses/{businessId}/upload/audience_csv — stage a CSV and get an asset id.

Manage audiences

Create, replace, read, and delete a stored recipient list.

Send to an audience

POST /v1/businesses/{businessId}/send/audience_campaigns — send now or on a schedule.

Send Campaigns

The inline alternative, for a small number of recipients per request.