Message Owl API Reference

Message Owl’s SMS API allows you to send and receive SMS messages to and from through a REST API. Each message is identified by a unique random ID so that users can always check the status of a message using the given endpoint.

The SMS API uses a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

API Endpoint

In order to use Message Owl APIs, you need to first sign up for free.




Message Owl’s APIs use API keys to authenticate requests. You can create, retrieve, and manage your API keys in your Message Owl Console.

With each API call, you will need to set request headers including your access key to authenticate yourself.

When your application can't send an Authorization header, you can use the GET parameter access_key to provide your access key.

Your API keys carry significant privileges. Please ensure to keep them 100% secure and be sure to not share your secret API keys in areas that are publicly accessible like GitHub. See API Access Key Security for more information.

Example Request

curl -i -H 'Authorization: AccessKey ZoeEG68M79w0QyM'

API Access Key Security

Given your API access key is your authentication token for using Message Owl’s APIs, they need to be appropriately secured. One of the easiest ways to think of this is to treat your API access keys just like you would your passwords, including storing them securely and never sharing them with anyone.

One of the most common mistakes that is made with API keys is to inadvertently check them into public repositories on platforms such as GitHub. From here, fraudsters can find and steal your API access key and then use it to send Spam messages and also drain your account balance. There are numerous techniques to avoid this, however storing your API access key in an environment variable, passing them as command line arguments or using a secrets manager can all help to prevent this from occurring. The main takeaway is don't hard-code your API access key and don't check it into a public code repository.

In a similar manner, sharing code snippets on platforms such as PasteBin, GitHub Gists or StackOverflow can inadvertently leak your API access key so ensure that you and your developers are aware of this risk.

Message Owl also takes measures on our side to help detect and mitigate compromised API access keys, however prevention is the best medicine so please ensure you protect your API access keys.

API Errors

Message Owl uses standard HTTP status codes to indicate the success or failure of an API request. Generally speaking, codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information provided (e.g., authentication, no balance or a missing or wrong parameter).

In case of an error, the body of the response includes a json formatted response that tells you exactly what is wrong.

HTTP Status Codes Description
200 ok We found the request resource
201 Created The resource is successfully created
204 No Content The requested resources is empty
401 Unauthorized The access key was incorrect
404 Not found The resources cannot be found
405 Method Not Allowed The method is not allowed
408 Request Timeout The request is taking too long to respond
422 Unprocessable Entity The resource couldn’t be created
5xx Something went wrong on our end Please try again

Error handling

The error object will give you information about the error makes it easier to fix.

Error Object

  "message": "Request not allowed (incorrect access_key)"


POST requests to the API should contain a JSON-formatted payload in the request body. Alternatively, resource attributes can be sent through GET parameters.

JSON request payload example

  "recipients": "9609848571",
  "sender_id": "MessageOwl",
  "body": "The message to be sent"

Rate Limits

Msgowl APIs are rate-limited to ensure the best experience for users. It refers to a group of limits set on number of requests that can be processed. The maximum number of requests that are allowed is based on a specified period. These limits help us provide the reliable and scalable API that our users can rely on. Additionally, it is important to note that the limits are calculated separately for each our services.

Types of rate limits

Type Method Allowed Calls Period
Request Per IP ANY 1000(200rmp) 5 minutes
Request Per Account POST 200 60 seconds

If you exceed a rate limit, server will return an error message that includes the encountered rate limit as well as how long you should wait before retrying.

HTTP headers and response

When a request is throttled examine HTTP headers that indicate when the limit resets and pause requests until then.

Header Description
RateLimit-Limit Rate limit for the given service.
RateLimit-Remaining Number of requests remaining.
RateLimit-Reset Time when rate limit resets, in UTC epoch seconds

When a user exceeds the rate limit , the API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:

  "message": "Too many requests. Please try again later",
  "retry_after": 1606321980

Start Building

If you have any questions, don’t hesitate to let us know at [email protected]; we’re here to help.

Was this helpful?