---
title: "Retrieve a broadcast"
description: "One broadcast with `counts` read live from its copies, which makes this the call to poll while it sends."
url: "https://nextmail.sh/docs/api/broadcasts/get"
area: "API"
category: "Mailbox"
---

# Retrieve a broadcast

One broadcast with `counts` read live from its copies, which makes this the call to poll while it sends.

`GET /broadcasts/{id}`

## GET /broadcasts/{id}

One broadcast with `counts` read live from its copies, which makes this the call to poll while it sends.

## Example

Needs `emails:read`.

**curl**

```
curl "$OE/broadcasts/brd_5a8c1e3f7b2d94a06c8e1f3b" -H "$AUTH"
```

**Response**

```
{
  "object": "broadcast",
  "id": "brd_5a8c1e3f7b2d94a06c8e1f3b",
  "status": "sending",
  "mode": "live",
  "source": "api",
  "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"],
  "from": "Acme <news@acme.com>",
  "subject": "{{firstName|Hello}}, the September release is out",
  "counts": {
    "recipients": 412,
    "created": 250,
    "skipped": 1,
    "failedToQueue": 0,
    "queued": 38,
    "sending": 2,
    "sent": 209,
    "failed": 1,
    "cancelled": 0
  },
  "lastError": null,
  "scheduledAt": null,
  "startedAt": "2026-09-23T12:00:02.000Z",
  "completedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-09-23T12:00:00.000Z",
  "updatedAt": "2026-09-23T12:00:41.000Z"
}
```

> An id from another workspace is a `404` `broadcast_not_found`, and so is a broadcast sent from an address or domain that a key limited to particular addresses or domains does not hold.

> For who each copy went to and what happened to it, list the copies with `GET /broadcasts/{id}/recipients` and read one with `GET /broadcasts/{id}/recipients/{emailId}`. `GET /broadcasts/{id}/stats` adds them up.

## Statuses

| Status | Means |
| --- | --- |
| scheduled | Waiting for `scheduledAt`. |
| queued | Waiting for the sending to start. |
| sending | Walking the audiences, or finished walking them while copies are still waiting to go. `completedAt` is set once the last person was reached. |
| sent | Every copy handed over has gone out or failed. |
| cancelled | Stopped by `POST /broadcasts/{id}/cancel`. |
| failed | The whole broadcast stopped: the `from` address can no longer be sent from, the template stopped resolving, the plan ran out part way, the sending itself kept failing, or not one copy could be written. `lastError` says which. |

## Counts

| Count | Means |
| --- | --- |
| recipients | The estimate taken when the broadcast was created. It does not move afterwards. |
| created | Copies written so far, one per person reached. |
| skipped | People passed over because their address was suppressed by the time the sending reached them. |
| failedToQueue | People whose copy could not be written. `lastError` names the most recent one. |
| queued, sending, sent, failed, cancelled | The copies by the state each one is in now, counted live. |

## Webhook events

Four events follow a broadcast: `broadcast.sending` when it starts going out, `broadcast.sent` when every copy has been handed over for sending, `broadcast.failed` when it stops because it cannot go out, and `broadcast.cancelled` when it is cancelled before it finishes. Each carries `broadcastId`, `status`, `subject`, `fromEmail`, `audienceIds`, `recipients`, `created`, `skipped`, `failed`, `error` and `at`.

> Every copy still sends its own `email.*` events as it goes, and `GET /broadcasts/{id}` reads `sending` until the last one has gone out. These four are not in the default set, so an endpoint receives them only when it names them in `eventTypes`, and an endpoint limited to some addresses or domains never does, because a broadcast goes to the audiences of the whole workspace.

## Reference

- [`GET /broadcasts/{id}`](https://nextmail.sh/docs/api/reference/broadcasts#get-broadcasts-id): full reference