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.
In order to use Message Owl APIs, you need to first sign up for free.
REST API Base URL
OTP API Base URL
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
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.
curl -i -H 'Authorization: AccessKey ZoeEG68M79w0QyM' https://rest.msgowl.com/balance
All the Rest API keys have scopes. Scopes define the endpoints to which the access key has permission to whether read or write. This allow you to limit API key to have access to only selected endpoints. Please refer documentation to find scopes required for each endpoint.
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 Consoles 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 Consoles 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.
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
|We found the request resource
|The resource is successfully created
204 No Content
|The requested resources is empty
|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
The error object will give you information about the error makes it easier to fix.
"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
JSON request payload example
"body": "The message to be sent"
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
|Request Per Account
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.
|Rate limit for the given service.
|Number of requests remaining.
|Time when rate limit resets, in UTC epoch seconds
|Seconds remaining to reset.
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",
If you have any questions, don’t hesitate to let us know at [email protected]; we’re here to help.