---
title: "Who would receive, without creating a campaign"
method: POST
path: "/api/v1/audience"
tags: ["Campaigns"]
---

# Who would receive, without creating a campaign

`POST /api/v1/audience`

## Request

- Base URL: `https://mailcheer.com`
- URL: `https://mailcheer.com/api/v1/audience`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Permission required: `subscribers:read`. **Read-only**: nothing is created, nothing is sent.

Returns what a campaign sent right now to the whole list would reach — restricted to `to` if given, with the same per-address breakdown as the send. To display "12 will receive, 3 are excluded" while someone chooses who to write to, without creating a draft.

Campaign-specific checks (subject, content, quota, segment) remain those of `dry_run` on `POST /api/v1/campaigns/{id}/send`.

## Request body

- object
  - `to` string[]: Optional. Restricts the send to these addresses — only those that are active subscribers of the audience, never an address on the suppression list. Omitted: the whole audience. Empty (`[]`): nobody, the send is refused.

## Response `200`

The recipient count, and the per-address breakdown if `to` is given.

- object
  - `object` 'audience'
  - `recipients` integer
  - `audience` Audience: The breakdown of a send restricted by `to`. The count always adds up: `requested = duplicates + retained + excluded`.
    - `requested` integer: Entries received in `to`, as sent.
    - `duplicates` integer: Entries repeating an address already seen (case and spaces ignored).
    - `retained` integer: Addresses that receive (or would receive) the campaign.
    - `excluded` integer: Excluded addresses.
    - `reasons` object: Excluded addresses per reason; every reason is present, even at zero.
      - `invalid` integer: Not an email address.
      - `not_in_list` integer: No subscriber of the workspace has this address.
      - `pending` integer: Sign-up not confirmed yet (double opt-in).
      - `unsubscribed` integer
      - `bounced` integer
      - `complained` integer
      - `suppressed` integer: Active subscriber, but the address is on the suppression list.
      - `outside_segment` integer: Active subscriber, outside the segment the campaign targets.
    - `excluded_addresses` object[]: Every excluded address, with its reason.
      - `email` string
      - `reason` 'invalid' | 'not_in_list' | 'pending' | 'unsubscribed' | 'bounced' | 'complained' | 'suppressed' | 'outside_segment'

## Other responses

- `401`: Key missing, unknown or revoked.
- `403`: The key does not have the requested permission, or the workspace cannot send: `sending_blocked` (suspended, blocked or banned — nothing goes out, through any channel), `commitment_required` (the anti-spam commitment is not accepted), `reputation_blocked` (too many bounces or complaints).
- `422`: Malformed field, unverified domain, or recipient on the suppression list.

---

[API](https://skmtc.dev/mailcheer/apis/mailcheer-api.md) · [All operations](https://skmtc.dev/mailcheer/apis/mailcheer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailcheer/apis/mailcheer-api/revisions/ba64b7ef2170?raw)