Skip to main content
CampaignsVersion: v3New

Estimate Recipients

POST/emails/locations/{locationId}/campaigns/recipients/estimate

Count how many contacts match an audience right now (contact, tag, segment, smart_list, custom_segment or all) and get a one-line summary to confirm with the user before scheduling. The count is before send-time suppression: do-not-disturb, unsubscribed and contacts without a valid email are skipped at send, so tell the user it is the most that can receive the campaign, not a delivery count. Returns the count only, never contact ids. Write-scoped because an exact count for any filter would otherwise let a read-only token enumerate contacts.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:emails/campaigns.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Path Parameters

locationIdstringrequired

Location ID

Example:ve9EPM428h8vShlRW1KT

Body

contactIdsstring[]

Required when type is contact

Example:["8eHQB5vTbGKdK9UWXL3G"]
tagIdsstring[]

Required when type is tag

Example:["6YMlGPn0LHi5OmJaXdLB"]
segmentstring

Required when type is segment

Available optionsengaged_last_7_daysengaged_last_30_daysengaged_last_60_daysengaged_last_5_campaignsunengaged_last_5_campaigns
Example:engaged_last_30_days
smartListIdsstring[]

Required when type is smart_list. Only the first is used.

Example:["f2a6b1c4-3d1e-4c8e-9a7b-2f4c6e8d0a1b"]
conditionsobject[]

Required when type is custom_segment

freezeListboolean

Freeze the contact list at schedule time

Example:false
typestringrequired

Who receives the campaign: contact (contactIds), tag (tagIds), segment, smart_list (smartListIds; first is used), custom_segment (conditions) or all (every contact in the location).

Available optionscontacttagsegmentsmart_listcustom_segmentall
Example:smart_list

Response

Success

typestringrequired

Audience type that was estimated.

Available optionscontacttagsegmentsmart_listcustom_segmentall
Example:smart_list
countnumberrequired

Contacts matching this audience right now, before send-time suppression. Contacts with email do-not-disturb, unsubscribed, or without a valid email are skipped when the campaign sends, so fewer may receive it.

Example:1240
descriptionstring

One-line summary to show the user before scheduling.

Example:Smart list