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

Authorization

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.

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

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 Account POST 1 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
Retry-After 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",
					"retry_after": 26
						}

Start Building

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

Send

https://rest.msgowl.com/messages

POST to schedule a message for instant delivery.

Allowed Scopes

message.write

Request payload example

Single Recipient

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

Multiple Recipients

{
					"recipients": "9609848571,9609876543", // comma separated string
					"sender_id": "MessageOwl",
					"body": "The message to be sent"
					}

{
					"recipients": ["9609848571","9609876543"], // array of strings
					"sender_id": "MessageOwl",
					"body": "The message to be sent"
					}

Response example

{
					"message": "Message has been sent successfully.",
					"id": 8848
					}

Balance

https://rest.msgowl.com/balance

GET to check current account balance.

Allowed Scopes

account.balance.read

Response example

{
					"balance": "130.6347",
					}

List Messages

https://rest.msgowl.com/messages

GET to fetch latest 100 messages.

Allowed Scopes

message.read
message.write
message.body.read(allow read body content)

Response example

{
  "id": 8848,
  "sms_header": "MessageOwl",
  "status": 4,
  "created_at": "2020-01-12T15:07:32.594+05:00",
  "body": "TEST MESSAGE THREE" // with scope `message.body.read`
},{
  "id": 8847,
  "sms_header": "MessageOwl",
  "status": 4,
  "created_at": "2020-01-12T15:06:32.594+05:00",
  "body": "TEST MESSAGE TWO" // with scope `message.body.read`
},{
  "id": 8846,
  "sms_header": "MessageOwl",
  "status": 4,
  "created_at": "2020-01-12T15:05:32.594+05:00",
  "body": "TEST MESSAGE ONE" // with scope `message.body.read`
}

Get Message

https://rest.msgowl.com/messages/:id

GET to fetch message by ID.

Allowed Scopes

message.read
message.write
message.body.read(allow read body content)

Response example

{
"id": 8848,
"sms_header": "MessageOwl",
"status": 4,
"created_at": "2020-01-12T15:07:32.594+05:00",
"account_id": 1,
"body": "TEST MESSAGE THREE" // with scope `message.body.read`,
"recipients": [{
  "id": 78963,
  "phone_number": "9609999999",
  "delivery_status": 1,
  "sms_status": 1,
  "delivered_on": "2020-01-12T15:07:33.454+05:00"
    }]
}

Send

https://otp.msgowl.com/send

POST to send an OTP message.

Request payload example

{
  "phone_number": "9609999999",
  "timestamp": "2020-03-03T08:32:50.231979481Z", /* optional: timestamp used to generate code */
  "code": "235311", /* optional: auto generated if not provided */
  "code_length": 8 /* optional: default to 6 */
}

Response example

{
  "id": 1,
  "phone_number": "9609999999",
  "timestamp": "2020-03-03T08:32:50.231979481Z"
}

Resend

https://otp.msgowl.com/resend

POST to resend an OTP message.

Request payload example

{
  "phone_number": "9609999999",
  "id": 8
}

Response example

{
  "id": 8,
  "phone_number": "9609999999",
  "timestamp": "2020-03-03T08:32:50.231979481Z"
}

Verify

https://otp.msgowl.com/verify

POST to verify an OTP code.

Request payload example

{
  "phone_number": "9609999999",
  "code": "352682"
}

Response example

{
  "id": 1,
  "phone_number": "9609999999",
  "status": true,
  "timestamp": "2020-03-03T08:32:50.231979481Z"
}