Skip to main content
Let’s get you up to speed on the basics of using the Helo API. The Helo API is built on REST principles. Our API uses the following base URL, requiring TLS/SSL: 
https://api.helo.com

​
Authentication

To authenticate, you need to add an Authorization header with your API key: 
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.
StatusDescription
200Successful request.
400The request was malformed or otherwise invalid. We usually respond with this code when JSON is malformed.
401The API key was invalid.
403The 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.
404The resource was not found.
422Validation 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.
429The rate limit was exceeded.
5xxIndicates 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"
           }
       ]
   }
}
FieldDescription
typeA link that refers to a description of the error in our documentation.
titleA short title for the error.
instanceThe API endpoint being called.
statusThe HTTP status code.
codeThe Helo error code.
detailA detailed description of the error.
requestIdA unique identifier for the request.
errorsA 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

CodeDescription
invalid_jsonThe JSON payload on the request was invalid or malformed.
validation_failedValidation error. Returned for 422 errors.
resource_limit_exceededYou’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_foundThe requested channel was not found.
invalid_channelA 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_unverifiedThe requested domain has not been verified.
account_forbiddenThe account being used is not currently allowed to send mail.
recipient_forbiddenOne of the recipients requested is not currently allowed.
recipients_suppressedAll of the recipients in the request are suppressed.
templating_errorThere was an error rendering the template in the request.
send_limit_exceededThe account has exceeded its free sending quota.