email-broadcasts

Get a broadcast's audience counts

Returns a live estimate of how many contacts the broadcast can reach, narrowing from everyone in its audience down to the ones the send would go to.

  • total is every contact in the audience.
  • addressable is how many of those have an email address.
  • sendable is how many addressable contacts are not suppressed for the broadcast's category.

A transactional broadcast still reaches a contact who unsubscribed from or complained about marketing mail. A marketing broadcast does not.

The estimate can change until the broadcast sends. The broadcast must have an audience selected; otherwise, the request returns 422.

These are audience numbers, and sending does not change them: after a send they still describe who the broadcast resolved to, not what happened to them. status says which of the two situations you are in. For delivery outcomes, read the broadcast's recipients for per-recipient status, its events for the raw feed, or email statistics by broadcast for the aggregates.

get/v1/email/broadcasts/{broadcast_id}/counts

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/broadcasts/{broadcast_id}/counts
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

broadcast_idstring required
Example:eb_01krdgeqcxet5s7t44vh8rt9mg

Broadcast identifier. Starts with eb_.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The broadcast's audience counts.

broadcast_idstring required
status'draft' | 'scheduled' | 'accepted' | 'sending' | 'sent' | 'canceling' | 'canceled' | 'failed' required

Where the broadcast itself has got to. This is separate from what happened to individual recipients, which the broadcast's own sent_count, delivered_count, bounced_count and complained_count tell you. Those four are fields on the broadcast, not on everything that carries this status, and reading the broadcast's recipients or its events gives the same outcomes one recipient at a time.

  • draft: Created, and not sent or scheduled yet.
  • scheduled: Due to send at scheduled_at. You can still edit it, and you can still change the time, right up until sending starts.
  • accepted: Taken for immediate sending. Nothing has gone out yet.
  • sending: On its way. Some recipients have been sent to and some have not.
  • sent: Every recipient has been sent to.
  • canceling: A cancellation is under way and the remaining sends are stopping.
  • canceled: The cancellation finished. Anything already on its way to a recipient when you canceled cannot be pulled back.
  • failed: The broadcast could not be sent. Reading the broadcast gives failure_reason, which says why. If it had already started sending, the recipients it reached keep their delivery status and carry on producing events.

A draft is deleted rather than canceled, because it was never sent.

totalinteger required

How many contacts are in the audience.

addressableinteger required

How many of those contacts have an email address. A contact with no address is not counted. This is never higher than total.

sendableinteger required

How many of the addressable contacts are not suppressed for this broadcast's category, which is who the email would actually go to. This is never higher than addressable. Which suppressions apply depends on the category, so the same audience can give a higher number for a transactional broadcast than for a marketing one. A transactional broadcast still reaches people who unsubscribed from or complained about marketing mail, and a marketing broadcast does not.

Example response

{
  "broadcast_id": "eb_01krdgeqcxet5s7t44vh8rt9mg",
  "total": 13000,
  "addressable": 12500,
  "sendable": 12000
}

Changes

No recorded changes to this operation across all 2 revisions of this API.