Broadcasts - Helo API

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

cURL

curl --location 'https://api.helohq.com/send/broadcast' \
--header 'X-Helo-Channel-Id: YOUR_CHANNEL_ID' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_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 up to 50 messages per second. 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 your MTA and 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:

Error code	Cause
`channel_not_found`	The channel does not exist or you don’t have access to it.
`domain_unverified`	The sender domain has not been verified on your account.
`account_forbidden`	Your account is not permitted to send (blocked, rejected, or cancelled).
`recipient_forbidden`	Pending accounts can only send to addresses on the same domain as the sender.
`recipients_suppressed`	All recipients in the request are on the suppression list.
`templating_error`	A template variable or syntax error was found in the subject, HTML, or text.
`send_limit_exceeded`	Pending accounts have a 1,000-email free-send limit.

Limits at a glance

Limit	Value
Recipients per message (`to` + `cc` + `bcc`)	50
Subject line length	256 characters
Tags per broadcast	5
Tag length	100 characters
Metadata fields	10
Metadata key length	50 characters
Metadata value length	100 characters
Total header size	5,000 characters
Email address length	254 characters
Processing rate	50 messages/second
Free-send limit (Pending accounts only)	1,000 emails
Max results per list query	500

​When to use broadcasts vs. individual messages

​The API

​Submit a broadcast

​Broadcast lifecycle

​Delivery rate

​Failures and suppressions

​Validation errors

​Limits at a glance