Transactional - Helo API

The transactional sending API lets you send a single email — or a small batch — with an immediate response. Use it for password resets, order confirmations, notifications, or any message triggered by a user action.

When to use individual sending vs. broadcasts

Use individual sending when you need a real-time response, want full per-message control, or are sending event-driven mail (one message per user action). Use broadcasts when you have a large list and want Helo to handle the delivery pipeline for you.

Sending a message

POST /send/transactional

There are two ways to provide message content: direct fields, or a template object.

Direct content

Use this for simple messages where the content is fully known ahead of time. Example request

cURL

curl --location 'https://api.helohq.com/send/transactional' \
--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>",
  "to": [{ "email": "jane@example.com", "name": "Jane" }],
  "subject": "Your order has shipped",
  "html": "<p>Hi Jane, your order #1234 is on its way.</p>",
  "text": "Hi Jane, your order #1234 is on its way.",
  "tags": ["transactional", "order"]
}'

Response

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

Template content

Use this when you want to populate content dynamically using {{variable}} placeholders. Move your subject, HTML, and text into a template object alongside a data map. Request

curl --location 'https://api.helohq.com/send/transactional' \
--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>",
  "to": [{ "email": "jane@example.com", "name": "Jane" }],
  "template": {
    "subject": "Hi {{firstName}}, your order has shipped",
    "html": "<p>Hi {{firstName}}, your order #{{orderId}} is on its way.</p>",
    "text": "Hi {{firstName}}, your order #{{orderId}} is on its way.",
    "data": {
      "firstName": "Jane",
      "orderId": "1234"
    }
  }
}'

When using template, top-level subject, html, and text fields must not be included — pick one approach or the other.

Response

status is one of:

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

A successful response always includes a messageId you can use for support lookups. If some recipients were on your suppression list, they appear in the suppressions array — the message still sends to the remaining recipients.

{
  "status": "accepted",
  "messageId": "01930f2a-4b3c-7d8e-9f0a-1b2c3d4e5f6a",
  "suppressions": ["previously-bounced@example.com"]
}

If all recipients are suppressed, the message is rejected with errorCode: "recipients_suppressed" rather than sending to no one.

Batch sending

POST /send/transactional/batch

Sends multiple messages in a single request. Each message is validated and processed independently — one failure does not affect the others. Example request

cURL

curl --location 'https://api.helohq.com/send/transactional/batch' \
--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 '{
  "requests": [
    {
      "from": "hello@acme.com",
      "to": [{ "email": "jane@example.com" }],
      "subject": "Your receipt",
      "html": "<p>Thanks, Jane.</p>"
    },
    {
      "from": "hello@acme.com",
      "to": [{ "email": "john@example.com" }],
      "subject": "Your receipt",
      "html": "<p>Thanks, John.</p>"
    }
  ]
}'

Response

{
  "responses": [
    { "status": "accepted", "messageId": "01930f2a-...", "suppressions": [] },
    { "status": "accepted", "messageId": "01930f2b-...", "suppressions": [] }
  ]
}

Idempotency

To prevent duplicate sends when retrying a failed request, include an idempotency key:

X-Helo-Idempotency-Key: your-unique-key-here

If Helo receives the same key with the same request body within one hour, it returns the original response without sending again. If the same key is reused with a different body, the request is rejected with HTTP 409. Idempotency only applies to successful responses — if a request fails, you can safely retry it with the same key.

Suppressions

Helo automatically checks every recipient against your channel’s suppression list before sending. Suppressed addresses (from previous bounces, unsubscribes, or manual additions) are silently removed from the To, Cc, and Bcc fields, and their addresses are returned in the suppressions array on the response. If you need to check whether an address is suppressed before submitting, use the Suppressions API.

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:

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 are on the suppression list.
`templating_error`	A `{{variable}}` placeholder or syntax error was found in the template.
`send_limit_exceeded`	Pending accounts have a 1,000-email free-send limit.

Channel selection

If your API credential is scoped to a specific channel, no extra configuration is needed. If you’re using an account-level credential, specify the channel in the request header:

X-Helo-Channel-Id: <channel-uuid>

Limits at a glance

Limit	Value
Recipients per message (`to` + `cc` + `bcc`)	50
Subject line length	256 characters
Email address length	254 characters
Tags per message	5
Tag length	100 characters
Metadata fields	10
Metadata key length	50 characters
Metadata value length	100 characters
Total header size	5,000 characters
Idempotency key length	36 characters
Idempotency window	1 hour
Free-send limit (Pending accounts only)	1,000 emails

​When to use individual sending vs. broadcasts

​Sending a message

​Direct content

​Template content

​Response

​Batch sending

​Idempotency

​Suppressions

​Tracking

​Validation errors

​Channel selection

​Limits at a glance