Skip to main content
POST
Ruby

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Helo-Channel-Id
string<uuid>

Used to specify a channel ID for sending when using an account-level API credential.

X-Helo-Idempotency-Key
string

A unique identifier used to prevent duplicate messages being sent when retrying failed requests.

Maximum string length: 256

Body

application/json
from
object
required
template
object
required

Email template applied to every message in the broadcast. At least one of html or text is required.

messages
object[]
required

One entry per outbound email. At least one message is required.

replyTo
object[]

Reply-to addresses.

tracking
object

Override channel-level open and link tracking settings.

attachments
object[]

File attachments included with every message in the broadcast. Executable and potentially harmful file types are blocked.

tags
string[]

Up to 5 tags for filtering and analytics. Allowed characters are letters, numbers, hyphens, and underscores. Max 100 characters per tag.

headers
object

Custom email headers applied to every message. Total size of all headers combined must not exceed 5,000 characters.

metadata
object

Custom key/value metadata stored with the broadcast. Max 10 fields; keys max 50 characters, values max 100 characters.

Response

OK

status
string

accepted — broadcast queued successfully. failed — validation or account error (see errorCode). delayed — transient submission error, will be retried automatically.

broadcastId
string<uuid>

Unique identifier for the broadcast. Use this to track progress via GET /broadcasts/{id}.