---
title: "Broadcast recipients"
method: GET
path: "/v1/sites/{site_id}/broadcasts/{broadcast_id}/recipients"
tags: ["Broadcasts"]
---

# Broadcast recipients

`GET /v1/sites/{site_id}/broadcasts/{broadcast_id}/recipients`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/broadcasts/{broadcast_id}/recipients`
- Auth: HTTP bearer

Target audience and sending progress. Before sending, including preparation,
`total` is an estimate (`total_is_estimate=true`); `sent` and `queued` are null.
After start, `total = sent + queued`. An unknown queue leaves both `queued`
and `total` null. Sent is not delivered; delivery counts are in `get_broadcast_stats`.

Example while sending: `{"sent":800,"queued":200,"total":1000,"total_is_estimate":false}`.

## Path parameters

- `site_id` integer, required
- `broadcast_id` integer, required: Broadcast id from `list_broadcasts`

## Response `200`

Successful Response

- BroadcastRecipients
  - `audience` AudienceCard, required
    - `segments` SegmentRef[], required: Segments the audience conditions refer to
      - `id` integer, required: Segment id from `list_segments`
      - `name` string, nullable: null when the segment was deleted: then nobody receives it
    - `has_other_conditions` boolean, required: true: the conditions also hold rules besides segments; `get_broadcast` has them all
    - `limit` integer, nullable: At most this many recipients; null when not limited
    - `all_contacts` boolean, required: true: the conditions select every subscribed contact, the admin's All contacts; it is stored as an empty list of segments
    - `conditions` object, nullable: Who receives the broadcast. Only subscribed contacts are sent to: that condition is always added and is not in the tree. The tree is written as segment conditions. Which contacts belong to the segment: a tree of conditions, applied to the contacts as they are at the moment it is used. Conditions are the condition language of the Getsitecontrol admin, with its own variable names and codes; they are not the field names and values of `Contact`. A segment written here can be edited in the admin, and the variables below are the ones the admin's condition editor offers. A node is an object with exactly `op` and `args`. A group has `op` `and` or `or` and nodes in `args`; a leaf has the variable `{{$contact.<name>}}` as the first argument, then its values: none for `*` (is set) and `undefined` (is not set), two for `between` and `!between`, one for the rest. To negate, use the opposite operator; there is no `not` node. The admin editor shows a root group whose `args` are groups, each holding leaves, as in the example; write that shape so the segment stays editable there. `{"op": "and", "args": []}` matches every contact of the site. Conditions are saved as sent. Values are integers, strings or, for `ina` and `!ina`, a list of them. | Operator | Meaning | |---|---| | `=`, `!=` | equals, differs | | `ina`, `!ina` | any of the list, none of it | | `<`, `>`, `between`, `!between` | compare; `between` includes both ends | | `^`, `$`, `in`, `match` (and `!`-forms) | starts with, ends with, contains, wildcard `*` without case | | `*`, `undefined` | is set, is not set | Text operators other than `match` are case sensitive, except on `$contact.email`: a contact's email is stored lowercase and compared without case by every operator. In `^`, `$`, `in`, `match` and their negations `_` matches any single character and `%` is a plain character. | Variable | Operators | Value | |---|---|---| | `$contact.email`, `phone`, `firstName`, `lastName` | text operators, `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | string | | `$contact.country` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | ISO 3166-1 alpha-2, upper case | | `$contact.date` | `=`, `!=`, `<`, `>`, `between`, `!between`, `*`, `undefined` | date the contact was added | | `$contact.isSubscribed` | `=` | marketing status: `S` subscribed, `U` unsubscribed, `B` bounced | | `$contact.emailQuality` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | `Corp+`, `Corp` corporate, `Pers+`, `Pers` personal (`+` is the higher grade), `Edu` education, `Gov` government, `Risk` risky, `Temp` disposable, `Unk` unknown | | `$contact.tags` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | tag ids from `list_tags` | | `$contact.segments` | `=`, `!=`, `ina`, `!ina` | ids from `list_segments`, as integers | | `$contact.emailSend`, `emailOpen`, `emailClick` | `=`, `!=`, `ina`, `!ina`, `*`, `undefined` | e-mail id, as `email_id` of a broadcast | | `$contact.emailSendCount`, `emailOpenCount`, `emailClickCount` | `=`, `!=`, `<`, `>`, `between`, `!between`, `*`, `undefined` | integer, not negative | | `$contact.emailSendDate`, `emailOpenDate`, `emailClickDate` | as `$contact.date` | the latest event | | `$contact.$shopifySpent`, `$shopifyOrders` | as the counts | integer | | `$contact.$shopifyOrderDate` | as `$contact.date` | the latest order | | `$contact.<field id>` | by the field type from `list_contact_fields`: text, integer, number, date or datetime | as the field; boolean and other fields are refused | `ina` and `!ina` on tags and segments take at least one id. On `$contact.tags`, `=` means the contact has that tag among its tags. `$contact.isSubscribed` compares the stored status code as the admin does: `S` does not match a contact who confirmed double opt-in, `U` does not match one who never subscribed or awaits double opt-in, and `B` matches every bounced contact. The contact statuses `subscribed`, `unsubscribed` and `bounced` are the broader groups. Ids are integers or strings of digits. A number is a 32-bit integer or a string holding one. A date is `YYYY-MM-DD` or ISO 8601 with an offset. For `$contact.date`, `$shopifyOrderDate` and datetime fields, a value at midnight is a whole day: `=` and `!=` cover the day, and the second value of `between` runs to its end. Date fields and `$contact.email*Date` compare with midnight exactly. Nested segments may not form a cycle. A list must reference each nested segment once, and not one nested inside another. Conditions are checked the way they run: nested segments must exist and the whole tree must compile, so an unknown variable or a value of the wrong type is refused. Conditions saved in the admin are returned as they are and may use other variables and values. null only together with non-empty `warnings`
    - `recipient_settings` RecipientSettings, required
      - `limit` integer, nullable: At most this many recipients; null when not limited
      - `sort` 'newest' | 'oldest' | 'random' | 'hottest', required: Which contacts a `limit` keeps: newest: added last. oldest: added first. random: a random choice. hottest: who opened or clicked most recently.
      - `quality_gate` EmailQualityGrade[], required: E-mail qualities left out of the audience; empty when none is
  - `sent` integer, nullable, required: E-mails sent so far, not delivered. Null before sending starts; zero if started but none sent.
  - `queued` integer, nullable, required: E-mails waiting to be sent. Null before sending starts or when unknown; zero when none remain.
  - `total` integer, nullable, required: Audience estimate before sending; sent plus queued after start. Null if the estimate or queue is unknown.
  - `total_is_estimate` boolean, required: True for drafts, scheduled broadcasts and audience preparation; false after sending starts.
  - `quality` object, nullable: Estimated total by e-mail quality for drafts and scheduled broadcasts; null otherwise. Ungraded contacts are `unknown`.

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `site_not_found`: no such site in your account; `broadcast_not_found`: the site has no broadcast with this id, or it was deleted
- `422`: Validation failed
- `429`: `rate_limited`: a limit of the key or the account is spent; statistics also spend the heavy request limit of the key. Retry after `Retry-After` seconds
- `503`: `temporarily_unavailable`: the numbers took too long to count or the limits cannot be checked right now; retry later or shorten the period

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)