Broadcasts

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

command-line

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

{
  "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.

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 for specific error codes.

Getting started

Core concepts

Platforms

When to use broadcasts vs. individual messages

The API

Submit a broadcast

Broadcast lifecycle

Delivery rate

Failures and suppressions

Validation errors

​When to use broadcasts vs. individual messages

​The API

​Submit a broadcast

​Broadcast lifecycle

​Delivery rate

​Failures and suppressions

​Validation errors

When to use broadcasts vs. individual messages

The API

Submit a broadcast

Broadcast lifecycle

Delivery rate

Failures and suppressions

Validation errors