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.

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.

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

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.

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
						}

Bulk Limit

Each bulk message sent through Msgowl APIs has a limit of 10,000 recipients per message.

The API will return a 422 status code accompanied by the following error object.

{
					"message": "Recipients exceeds allowed limit of 25000"
"bulk_limit": 25000
						}

Start Building

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

Balance

https://rest.msgowl.com/balance

GET to check current account balance.

Allowed Scopes

Response example

{
					"balance": "130.6347",
					}

Messages

Send

https://rest.msgowl.com/messages

POST to schedule a message for instant delivery.

Allowed Scopes

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
					}

List Messages

https://rest.msgowl.com/messages

GET to fetch latest 100 messages.

Allowed Scopes

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

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

Delivery statuses

We offer two types of delivery statuses: delivery_status, which represents the current status of the recipient for the message within Msgowl, and sms_status, which reflects the delivery status reported by the service provider.

Groups

Create

https://rest.msgowl.com/groups

POST to create a new group.

Allowed Scopes

Request payload example

{
					"name": "The Group"
					}

Response example

{
					"id": 22
					"name": "The Group",
					"account_id": 1,
					"user_id": 1,
					"created_at": "2020-01-12T15:05:32.594+05:00",
					"updated_at": "2020-01-12T15:05:32.594+05:00"
					}

Update

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

PUT to update a group.

Allowed Scopes

Request payload example

{
					"name": "The New Group"
					}

Response example

{
"id": 22
"name": "The New Group",
"account_id": 1,
"user_id": 1,
"created_at": "2020-01-12T15:05:32.594+05:00",
"updated_at": "2020-01-12T15:05:32.594+05:00",
					}

List

https://rest.msgowl.com/groups

GET to fetch all groups.

Allowed Scopes

Response example

{
  "id": 22,
  "name": "The Group"
  "account_id": 1,
  "user_id": 1,
  "created_at": "2020-01-12T15:05:32.594+05:00",
  "updated_at": "2020-01-12T15:05:32.594+05:00",
},{
  "id": 23,
  "name": "Msgowl"
  "account_id": 1,
  "user_id": 1,
  "created_at": "2020-01-12T15:05:32.594+05:00",
  "updated_at": "2020-01-12T15:05:32.594+05:00",
},{
  "id": 24,
  "name": "Oxiqa"
  "account_id": 1,
  "user_id": 1,
  "created_at": "2020-01-12T15:05:32.594+05:00",
  "updated_at": "2020-01-12T15:05:32.594+05:00",
}

Fetch

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

GET to fetch a group.

Allowed Scopes

Response example

{
 "id": 22,
  "name": "The Group"
  "account_id": 1,
  "user_id": 1,
  "created_at": "2020-01-12T15:05:32.594+05:00",
  "updated_at": "2020-01-12T15:05:32.594+05:00",
  "contacts": [{
    "id": 1232,
    "name": "Customer",
    "number": "9609999999"
  }]
}

Remove

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

DELETE to remove a group.

Allowed Scopes

Response example

{
					"message": "Group destroyed successfully.",
					}

Contacts

Create

https://rest.msgowl.com/contacts

POST to create a new contact.

Allowed Scopes

Request payload example

{
  "name": "Customer",
  "number": "9609999999",
  "group_names": ["The Group", "Oxiqa"]
}

Response example

{
"id": 1232,
"name": "Customer",
"number": "9609999999",
"created_at": "2020-01-12T15:05:32.594+05:00",
"updated_at": "2020-01-12T15:05:32.594+05:00",
"groups": [{
  "id": 22,
  "name": "The Group"
      }, {
  "id": 24,
  "name": "Oxiqa"
    }]
}

Update

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

PUT to update a contact.

Allowed Scopes

Request payload example

{
"name": "Customer Updated",
"number": "9609999999",
"group_names": ["The Group"]
}

Response example

{
"id": 1232,
"name": "Customer Updated",
"number": "9609999999",
"created_at": "2020-01-12T15:05:32.594+05:00",
"updated_at": "2020-01-12T15:05:32.594+05:00",
"groups": [{
  "id": 22,
  "name": "The Group"
      }]
}

List

https://rest.msgowl.com/contacts

GET to fetch contacts by 100 records.

Allowed Scopes

Query Params

Response example

{
"contacts": [{
    "id": 1232,
    "name": "Customer",
    "number": "9609999999",
    "account_id": 1,
    "user_id": 1,
    "created_at": "2020-01-12T15:05:32.594+05:00",
    "updated_at": "2020-01-12T15:05:32.594+05:00"
    },{
    "id": 1233,
    "name": "Another Customer",
    "number": "9609999997",
    "account_id": 1,
    "user_id": 1,
    "created_at": "2020-01-12T15:05:32.594+05:00",
    "updated_at": "2020-01-12T15:05:32.594+05:00" }],
"current_page": 1,
"next_page": 2,
"previous_page": null
}

Remove

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

DELETE to remove a contact.

Allowed Scopes

Response example

{
					"message": "Contact destroyed successfully.",
					}

OTP

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",
  "message_id": 1234
}

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",
  "message_id": 1234
}

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

Sender IDs

https://rest.msgowl.com/sms_headers

GET to list all sender IDs.

Allowed Scopes

Response example

[{
  "id": 1,
  "name": "MSGOWL",
  "purpose": "organization",
  "status": "pending verification",
  "created_at": "2022-12-14T12:46:41.519+05:00",
  "updated_at": "2022-12-14T12:49:18.203+05:00",
  "remarks": "Please upload a photo",
  "handled_at": null
},
{
  "id": 2,
  "name": "OXIQA",
  "purpose": null,
  "status": "approved",
  "created_at": "2022-05-10T14:40:15.408+05:00",
  "updated_at": "2023-01-07T12:00:39.123+05:00",
  "remarks": null,
  "handled_at": "2022-05-10T14:40:33.901+05:00"
}]