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.

REST API Base URL

https://rest.msgowl.com

OTP API Base URL

https://otp.msgowl.com

Authentication

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' https://rest.msgowl.com/balance

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)"
}

Requests

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"
}

Start Building

If you have any questions, don’t hesitate to let us know at support@msgowl.com; we’re here to help.

Was this helpful?

Next: REST API