> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helohq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcasts

> Ideal for sending to large recipient lists

Broadcasts let you send a single email campaign to a large list of recipients — think newsletters, product announcements, or promotional emails. Rather than sending individual messages one at a time, you submit the entire campaign in a single API call, and Helo handles delivery at scale.

## When to use broadcasts vs. individual messages

Use **broadcasts** when you have a list of recipients who all receive a variation of the same template-driven email. Use the standard **send** endpoint when you need per-message control, transactional timing, or real-time responses.

## The API

### Submit a broadcast

```
POST /send/broadcast
```

Submits a broadcast for processing. Helo validates the request, stores the content, and begins sending as soon as your channel is available.

**Example request**

```bash command-line theme={null}
curl --location 'https://api.helohq.com/send/broadcast' \
--header "X-Helo-Channel-Id: $HELO_CHANNEL_ID" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer $HELO_API_KEY" \
--data-raw '{
  "from": "Acme <hello@acme.com>",
  "replyTo": ["support@acme.com"],
  "template": {
    "subject": "Your monthly update, {{firstName}}",
    "html": "<p>Hi {{firstName}},</p><p>Here's what's new...</p>",
    "text": "Hi {{firstName}}, here's what's new...",
    "data": {
      "companyName": "Acme"
    }
  },
  "messages": [
    {
      "to": ["jane@example.com"],
      "data": { "firstName": "Jane" }
    },
    {
      "to": ["john@example.com"],
      "data": { "firstName": "John" }
    }
  ],
  "tags": ["newsletter", "june-2025"],
  "tracking": {
    "opens": true,
    "links": true
  }
}'
```

**Response**

```json theme={null}
{
  "status": "accepted",
  "broadcastId": "01930f2a-4b3c-7d8e-9f0a-1b2c3d4e5f6a"
}
```

`status` is one of:

| Value      | Meaning                                                                    |
| ---------- | -------------------------------------------------------------------------- |
| `accepted` | Broadcast queued successfully. Use `broadcastId` to track progress.        |
| `failed`   | Validation error. The response includes an `errorCode` and `errorMessage`. |
| `delayed`  | Transient error during submission. Helo will retry automatically.          |

For additional details about the API, see our [API reference](/api-reference/sending/send-a-broadcast-email).

## Broadcast lifecycle

```
Accepted → Processing → Completed
```

| Status       | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `Accepted`   | Broadcast has been validated and queued. Processing will begin when your channel is ready.          |
| `Processing` | Messages are actively being sent. Poll `GET /broadcasts/{id}` to track the `completion` percentage. |
| `Completed`  | All messages have been processed. Some may have failed — check `/failures` and `/suppressions`.     |
| `Cancelled`  | The broadcast was cancelled before completing.                                                      |

**One broadcast per channel at a time.** If your channel already has a broadcast in `Processing`, additional broadcasts queue in `Accepted` and start automatically when the current one finishes. Broadcasts are processed in the order they were submitted.

## Delivery rate

Helo processes broadcasts at an appropriate rate in order to maintain good deliverability. The more messages a given broadcast has, the more time it will take to complete. As a rough guide:

| List size | Estimated processing time |
| --------- | ------------------------- |
| 10,000    | \~3 minutes               |
| 50,000    | \~17 minutes              |
| 100,000   | \~33 minutes              |
| 500,000   | \~2.8 hours               |

These are processing times, not inbox delivery times. Actual inbox delivery depends on recipient mail servers.

## Failures and suppressions

After a broadcast completes, two categories of undelivered recipients are available:

**Failures** — permanent errors that prevented delivery, such as invalid addresses or domain issues. Retrieve them at `GET /broadcasts/{id}/failures`. Each failure includes the recipient list, message index, error code, and a description.

**Suppressions** — recipients skipped because they appear on your suppression list (previous bounces, unsubscribes, or manual suppressions). Retrieve them at `GET /broadcasts/{id}/suppressions`.

Transient errors (temporary network or service issues) are retried automatically and do not appear in the failures list unless they ultimately cannot be delivered.

## Validation errors

If the API returns `"status": "failed"`, the response includes an `errorCode`.

See [API overview](/api-reference/overview#error-codes) for specific error codes.