Campaign audiences

A campaign audience is the set of recipient records attached to that campaign. It is related to your CRM selection, but it is not simply a live tag or a count of search results. Prepare a campaign draft, choose its audience, and inspect the resulting addresses before sending.

Use the right access and IDsCopy Anchor Link

Personal tokens need both campaigns:read and contacts:read to inspect recipients, and both campaigns:write and contacts:read to add or remove them. The owner must have the corresponding email/contact permissions. The saved-source PATCH described below currently requires an integration key; it is not available to personal tokens.

A campaign uses a numeric ID. A CRM contact also has a numeric ID. Each campaign recipient has its own string id: use that returned recipient ID for recipient detail/removal, rather than substituting a contact ID.

Start with an explicit contactCopy Anchor Link

Get the campaign and confirm its ID, subject, sender, linked story, and lifecycle_status: draft. Get the contact, confirm the person and chosen email address, then replace YOUR_CAMPAIGN_ID and the illustrative numeric contact ID below:

curl --fail-with-body --silent --show-error --request POST 'https://api.prezly.com/v2/campaigns/YOUR_CAMPAIGN_ID/recipients' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"contact":{"id":12345}}'

The primary contact address is used by default. The optional contact.email_address selects another address belonging to that contact. Verify the returned recipient address: do not use an arbitrary external address as an override. The single-contact implementation can fall back to the primary address when an override does not belong to the contact.

A synchronous addition returns campaign, warnings, message, and notifications. Read the structured warnings/notifications, then inspect recipients. A success response does not prove that every selected contact was added or that every address can be sent to.

Add Campaign Recipients →

Inspect the actual audienceCopy Anchor Link

curl --fail-with-body --silent --show-error --get 'https://api.prezly.com/v2/campaigns/YOUR_CAMPAIGN_ID/recipients' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'sort=+id'

The response contains recipients, pagination, and sort. Check each recipient's email_address, underlying contact, address statuses, newsroom unsubscription, and account-wide unsubscription. The reference also lists filters for invalid, bounced, or duplicate addresses. Traverse all pages when reviewing a complete audience; do not present the first page as the full sending list.

Different contacts can share an email address. Adding contact IDs is not a promise to send once to every record, and recipient count alone does not describe eligibility. Inspect duplicates and suppression warnings rather than trying to bypass them. A contact's presence in your CRM does not establish permission to email it.

List Recipients → · Get Recipient →

Choose a larger audience deliberatelyCopy Anchor Link

Add Campaign Recipients accepts alternative selector shapes. Send one selector form per request rather than combining unrelated top-level selectors.

The reference documents per-request limits. Large additions can return 202 Accepted with progress.id instead of a completed campaign response. Persist the job ID and resolve it using Get Job Status with an integration key. Do not keep submitting the addition while it is in progress. Personal tokens cannot poll that endpoint; use an integration key for an automation that needs deferred completion, or reconcile recipient reads before continuing.

Distinguish adding recipients from replacing saved sourcesCopy Anchor Link

A campaign can also keep audience_selection_data: the rules describing how its audience was chosen. Changing that metadata through a general campaign update is not the same operation as applying recipient changes.

Use Update Campaign Audience Sources when you intend to change saved sources and apply their recipient changes together. This requires an integration key. For example, save this as audience-sources.json, replacing the illustrative tag ID:

{
  "tags": { "included": [42], "excluded": [], "match": "any" }
}

curl --fail-with-body --silent --show-error --request PATCH 'https://api.prezly.com/v2/campaigns/YOUR_CAMPAIGN_ID/recipients/audience-selection' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @audience-sources.json

Only supplied sources are replaced; omitted sources stay unchanged. Empty lists clear a source; clear tags by supplying empty included/excluded lists. Recipients outside the changed sources are retained, including contacts still selected by another source. Do not assume replacing one tag source replaces the entire campaign audience. Large additions can return a deferred job, even though the new sources have already been saved.

Remove a recipient without deleting the contactCopy Anchor Link

Use the string ID returned from the recipient list:

curl --fail-with-body --silent --show-error --request DELETE 'https://api.prezly.com/v2/campaigns/YOUR_CAMPAIGN_ID/recipients/YOUR_RECIPIENT_ID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json'

This removes the selected campaign recipient. It does not delete the CRM contact, unsubscribe them, or recall an email already sent. Leave the separate deactivate option out unless you deliberately intend to deactivate the underlying email address too.

Remove multiple recipients accepts a query; an omitted/empty query can remove the whole audience. Preview the exact selection rather than using a broad DELETE to experiment. Re-read the final audience and campaign warnings before continuing to testing and sending.