Audiences

The audience object

The subscriber object

status is one of subscribed, unsubscribed, bounced, complained, suppressed, or transactional_only. merge_fields holds up to 50 string, number, boolean, or null values keyed by field name.

Create an audience

Scope: audiences:write. Body: { name, description?, consent_source }. consent_source is a required attestation of where and how these people opted in. Returns the audience object with a 201.

List, get, update, and delete audiences

List supports cursor and limit pagination. Update accepts { name?, description? }. Delete returns 204 and removes the audience's subscribers; newsletters you already sent keep their history.

Add a subscriber

Scope: audiences:write. This is the endpoint your signup form calls. Body:

Returns a per-row outcome rather than the subscriber, so a suppressed or invalid address never errors the request:

outcome is one of created, updated, skipped_not_mailable, skipped_invalid, skipped_cap, or skipped_quota. The returned email_address is the normalized (trimmed, lowercased) form of what you sent.

Re-adding an existing subscriber merges instead of overwriting: a provided display_name replaces the stored one (omitting it keeps it), merge_fields keys you send are merged into the stored object, and consent is re-attested. To replace fields wholesale, use the update endpoint below.

Add subscribers in bulk

Add up to 1000 subscribers in one call. Body: { subscribers: [ ... ] } where each entry has the same shape as a single add. Returns { results: [ ... ] } with one outcome per row, in order. Request bodies are capped at 1 MB, so very large merge_fields payloads may need smaller batches.

Limits

Each audience holds up to 10,000 subscribed members. Net-new adds also count against a monthly ingest quota: 5,000 on Solo, 25,000 on Pro, and 100,000 on Team. Re-adds of existing subscribers are free. Adds over the cap return skipped_cap; adds over the quota return skipped_quota.

Quota admission is per call: if the remaining quota cannot admit every net-new address in a batch, the whole batch of net-new addresses is returned as skipped_quota. Retry with a smaller batch to use what remains. Audience ingest is not available during the free trial, so every net-new add returns skipped_quota until the trial converts.

List and look up subscribers

List supports cursor, limit, a status filter, and an exact email filter. The by-email lookup expects a URL-encoded address.

Update, unsubscribe, and remove

Update accepts { display_name?, merge_fields? }. Unsubscribe writes an organization-wide opt-out so future newsletters skip the address, and returns the updated subscriber. Delete returns 204; prefer unsubscribe to preserve opt-out history.