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. We also provide engagement and deliverability insights over individual broadcasts, offering helpful feedback on the performance of your campaigns.

When to use broadcasts

Use broadcasts when you have a list of recipients who all receive a variation of the same template-driven email, and the content is information/promotional in nature rather than driven by user actions.

This category of email can be prone to spam complaints and unsubscribes if you’re not careful about managing your contact lists (recipients should not be surprised they received an email from you!).These messages must contain unsubscribe links (don’t worry, we take care of that for you).

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

$ HELO_CHANNEL_ID='your-channel-id'
$ HELO_API_KEY='your-api-key'
$ 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 @- <<EOF
{
  "from": { "email": "from@your-domain.com" },
  "replyTo": [{ "email": "reply@your-domain.com" }],
  "template": {
    "subject": "Your monthly update from {{companyName}}",
    "html": "<p>Hi {{firstName}},</p><p>Here's what's new...</p>",
    "text": "Hi {{firstName}}, here's what's new...",
    "data": {
      "companyName": "Helo Test Co"
    }
  },
  "messages": [
    {
      "to": [{ "email": "recipient@recipient-domain.com" }],
      "data": { "firstName": "Jane" }
    }
  ],
  "tags": ["newsletter", "june-2025"],
  "tracking": {
    "opens": true,
    "links": true
  }
}
EOF

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.

Send a broadcast message

POST /send/broadcast/message

Sends just a single broadcast message. Use this when you want to send promotional email one-at-a-time, require immediate per-message feedback, and you don’t want all of the features broadcasts offer (ie. controlled processing rates, campaign performance metrics).

This API does not create a broadcast object, and many of the features mentioned in this document will not apply. It functions much the same way as the Send transactional API, only it creates messages of type broadcast instead.

Example request

command-line

$ HELO_CHANNEL_ID='your-channel-id'
$ HELO_API_KEY='your-api-key'
$ curl --location 'https://api.helohq.com/send/broadcast/message' \
--header "X-Helo-Channel-Id: $HELO_CHANNEL_ID" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer $HELO_API_KEY" \
--data @- <<EOF
{
  "from": { "email": "from@your-domain.com" },
  "to": [{ "email": "recipient@recipient-domain.com", "name": "Jane" }],
  "subject": "Your monthly update from Helo Test Co",
  "html": "<p>Hi Jane,</p><p>Here's what's new...</p>",
  "text": "Hi Jane, here's what's new...",
  "tags": ["newsletter", "june-2025"],
  "tracking": {
    "opens": true,
    "links": true
  }
}
EOF

Response

{
  "status": "accepted",
  "messageId": "01930f2a-4b3c-7d8e-9f0a-1b2c3d4e5f6a",
  "suppressions": []
}

status is one of:

Value	Meaning
`accepted`	Message accepted and queued for delivery.
`delayed`	Transient error during submission. Helo will retry automatically.
`failed`	Validation error. The response includes an `errorCode` and `errorMessage`.

Just like transactional sending, you can supply content directly (as above) or via a template object, and Helo checks the recipients against your channel’s suppression list — any suppressed addresses are removed and returned in the suppressions array. 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 status 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	~15 minutes
50,000	~1 hour
100,000	~2 hours

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

This is somewhat dependent on your sending domain’s history - inbox providers do not look kindly on significant increases in sending volume. Large spikes from your domain will result in deliverability issues, so there’s a limit to how much we can control there.Feel free to reach out to discuss your sending volume - it is our top priority to ensure your deliverability remains pristine, and we’re more than happy to work with you to achieve that.

Failures and suppressions

After a broadcast completes, two categories of undelivered recipients are available: Failures — permanent errors that prevented delivery, such as template rendering 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.

Tracking

By default, open and link tracking follow your channel settings. Override them per-message with the tracking object:

{
  "tracking": {
    "opens": true,
    "links": false
  }
}

Validation errors

If the API returns "status": "failed", the response includes an errorCode. See API overview for specific error codes.

Unsubscribe links

You can control where unsubscribe links appear (and what they look like) via a special tag: {{{ helo: unsubscribe }}}. When processing messages for delivery, we’ll replace this placeholder with an unsubscribe link tailored for each recipient. If you don’t provide this placeholder, we’ll automatically insert our own at the end of the email. However we strongly recommend you include it yourself for full control over the appearance of these links.

Getting started

Core concepts

Platforms

Account management

When to use broadcasts

The API

Submit a broadcast

Send a broadcast message

Broadcast lifecycle

Delivery rate

Failures and suppressions

Tracking

Validation errors

Unsubscribe links

​When to use broadcasts

​The API

​Submit a broadcast

​Send a broadcast message

​Broadcast lifecycle

​Delivery rate

​Failures and suppressions

​Tracking

​Validation errors

​Unsubscribe links

When to use broadcasts

The API

Submit a broadcast

Send a broadcast message

Broadcast lifecycle

Delivery rate

Failures and suppressions

Tracking

Validation errors

Unsubscribe links