https://api.helohq.com
Authentication
To authenticate, you need to add anAuthorization header with your API credentials:
Authorization: Bearer API_KEY
Errors and response codes
To show you if your requests to Helo were successful (or not), we’re using a combination of standard HTTP codes and our own custom validation error codes.| Status | Description |
|---|---|
200 | Successful request. |
400 | The request was malformed or otherwise invalid. We usually respond with this code when JSON is malformed. |
401 | The API key was invalid. |
403 | The API key does not have access to perform the requested operation, either because it lacks adequate permissions or because the account or Channel associated with the API key is different from what is associated with the requested action/resource. |
404 | The resource was not found. |
422 | Validation error. The request contained an invalid value for a specific property or a required property was missing. In most (but not all) cases, the response will include an errors property with additional error codes. See error codes below for more details. |
429 | The rate limit was exceeded. |
5xx | Indicates an error with Helo servers. This should happen infrequently. Otherwise, check our status page or contact us. |
Error response format
{
"type": "https://docs.helohq.com/errors#validation_failed",
"title": "Validation Failed",
"instance": "POST /channels",
"status": 422,
"code": "validation_failed",
"detail": "One or more fields were invalid.",
"requestId": "0HNL29NEOHAS9:00000004",
"errors": {
"/name": [
{
"message": "Must not exceed 100 characters. 142 characters were provided.",
"code": "max_length"
}
]
}
}
| Field | Description |
|---|---|
type | A link that refers to a description of the error in our documentation. |
title | A short title for the error. |
instance | The API endpoint being called. |
status | The HTTP status code. |
code | The Helo error code. |
detail | A detailed description of the error. |
requestId | A unique identifier for the request. |
errors | A dictionary where each key corresponds to the field on the request that caused the error and each value has a list of errors, composed of message and code. The errors property may not always be populated, depending on the nature of the error. |
General error codes
| Code | Description |
|---|---|
invalid_json | The JSON payload on the request was invalid or malformed. |
validation_failed | Validation error. Returned for 422 errors. |
resource_limit_exceeded | You’ve reached the limit for the given resource, e.g., you’re trying to create a Channel but have reached the maximum Channel limit for your account. |
channel_not_found | The requested Channel was not found. |
invalid_channel | A valid Channel ID is required for sending. Either the API credential must be associated with a channel ID or the X-Helo-Channel-Id header must be set. |
domain_unverified | The requested domain has not been verified. |
account_forbidden | The account being used is not currently allowed to send mail. |
recipient_forbidden | One of the recipients requested is not currently allowed. |
recipients_suppressed | All of the recipients in the request are suppressed. |
templating_error | There was an error rendering the template in the request. |
send_limit_exceeded | The account has exceeded its free sending quota. |
API limits
| Limit | Value |
|---|---|
Recipients per message (to + cc + bcc) | 50 |
| Tags per message/broadcast | 5 |
| Tag length | 100 characters |
| Subject line length | 256 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 |
| Idempotency key length | 36 characters |
| Idempotency window | 1 hour |