Bulk SMS API

Our Bulk SMS API allows you to send one-way sms to a single phone number or multiple phone numbers – anywhere in the world. Each message can be different, i.e., with one API request you can send different messages to different phone numbers.

This SMS API is extremely fast, highly available, and very easy to use.  We also offer delightful customer support for all of our APIs via live chat, email, and phone.

Check out our SMS rates by country on our pricing page.

Delivery receipts are available for every message sent via the API.

HTTP Method & Headers

The HTTP method is POST using this URL:

https://api.engagespark.com/v1/messaging/sms/phonenumbers

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {API_KEY}
Content-type application/json

Note: Replace {API_KEY} with your actual API Key from your account. Find it in your profile under Account Settings > API Key (https://ui.engagespark.com/#/api/docs).

Request Body Definition

Below are the only details we need and you need to provide in order for you to successfully send an SMS using the API:

Key Description Data Type Required Example
orgid The id of user’s organization. Find it in your organization profile (https://ui.engagespark.com/#/organizations/details). Integer Yes 1234
messages This contains the list of messages for bulk SMS or just a single message to an individual number. List[object] Yes

[

 

 

{

“to”: “639163284852”,

“from”: “engageSPARK”,

“message”: ” Sample message to you.”

}

 

]

to The mobile number of the SMS recipient. String Yes 639123456789
from The organization’s caller/sender ID or organization’s local phone number (virtual number – for 2-way SMS). Most countries require sender IDs to be pre-registered. If you set an ID here and you receive the message with an ID other than the one you set, contact us to pre-register one for branding purposes. Click here to know more about sender IDs. String Yes engageSPARK or 12345678
message The message content to be sent to the recipient. String Yes Sample message to you.
 

Sample JSON (for individual mobile numbers):

{

    "orgid": 1234,

    "messages": [

       {

            "to": "639123456789",

            "from": "engageSPARK",

            "message": " Sample message to you."

        }       

    ]  

}

Sample JSON (for bulk mobile numbers):

{

    "orgid": 1234,

    "messages": [

       {

            "to": "639123456789",

            "from": "engageSPARK",

            "message": "Sample message to you."

        },

       {

            "to": "254771234567",

            "from": "MyCompanyName",

            "message": "Have a great day."

        },

       {

            "to": "13105551212",

            "from": "13105551234",

            "message": "This is a sample message."

        }       

    ]  

}

Note: There is no hard limit to the number of messages you can send in bulk.

Response Body Definition

Below are the details that will be returned after every Bulk SMS API request:

Key Description Data Type Example
error Shows an error message if an error occurred. String invalid JSON document
estimateMicro Shows the cost estimate of the whole batch of messages. Divide by 1,000,000 to get the $ (USD) equivalent. Integer 20000
estimate Shows the estimated cost of the batch of messages in $ (USD). String 0.02
acceptedMessages The total number of messages we sent. Number 1
deliveryDeadline Shows the date and time until when we will retry to deliver the batch of messages in cases of network errors. String(Timestamp) 2019-07-02T05:21:54.837208837Z
messages Corresponds to the list of messages in the API request. List[object]

[

 

{

“id”: “SMS20190701T052154-123-1234-0”,

“estimateMicro”: 20000,

“estimate”: “0.02”,

“error”: “”

}

]

[{id}] Message ID. String SMS20190701T052154-123-1234-0
[{estimateMicro}] The cost estimate of a message in a list. Divide by 1,000,000 to get the $ (USD) equivalent. Integer 20000
[{estimate}] The estimated cost of a message in a list in $ (USD). String 0.02
[{error}] Shows an error message if an error occurred in a list. String empty message

Sample JSON Response (for individual mobile numbers):

{

    "error": "",

    "estimateMicro": 20000,

    "estimate": "0.02",

    "acceptedMessages": 1,

    "deliveryDeadline": "2019-07-02T05:21:54.837208837Z",

    "messages": [

        {

            "id": "SMS20190701T052154-123-1234-0",

            "estimateMicro": 20000,

            "estimate": "0.02",

            "error": ""

        }

    ]

}

Sample JSON Response (for bulk mobile numbers):

{

    "error": "",

    "estimateMicro": 60000,

    "estimate": "0.06",

    "acceptedMessages": 3,

    "deliveryDeadline": "2019-07-02T05:31:21.814068733Z",

    "messages": [

        {

            "id": "SMS20190701T053121-123-1235-0",

            "estimateMicro": 20000,

            "estimate": "0.02",

            "error": ""

        },

        {

            "id": "SMS20190701T053121-123-1236-1",

            "estimateMicro": 20000,

            "estimate": "0.02",

            "error": ""

        },

        {

            "id": "SMS20190701T053121-123-1237-2",

            "estimateMicro": 20000,

            "estimate": "0.02",

            "error": ""

        }

    ]

}

Note: For the Philippines, telcos have a 5 sms per mobile number per minute (5 sms/number/minute) capping rule. If you are sending more than 5 sms to a single number within a minute, some messages may not get through and will be lost.

The Bulk SMS API automatically re-tries failed messages as often as possible within 24 hours by default. To know up to when we’ll keep retrying your message, you can refer to the deliveryDeadline of your POST request.

Phone Number Formats

Phone numbers in the API need to have an international dialing code.

For example, for a number from Kenya (with the dialing code 254), 254771234567 would be correct, whereas 771234567 or 0771234567 would be missing the dialing code. If you are not sure about the dialing code of the country you want to send calls or SMS to, check our pricing page (scroll to the bottom).

SMS Status and Delivery Receipt

With every SMS that you send, you can make a GET request to check the SMS Status if the message was delivered to the recipient or not.

HTTP Method & Headers

The HTTP method is GET using this URL:

https://api.engagespark.com/v1/organizations/[organizationId]/messages/[messageId]/

Note: Replace [organizationId] (e.g., 1234) with your orgId and [messageId] (e.g., SMS20190701T053121-123-1235-0) with your message’s Id. Don’t forget to remove the brackets [].

You’ll need to set the following HTTP Headers:

Key Value
Authorization Token {API_KEY}
Content-type application/json

Sample JSON Response:

{

    "id": "SMS20190701T053121-123-1235-0",

    "direction": "egress",

    "created": "2019-07-01T05:31:21.814069Z",

    "sender": "engageSPARK",

    "recipient": "639123456789",

    "contactId": 0,

    "engagementId": 0,

    "engagementFlowId": 0,

    "engagementRunId": 0,

    "engagementPartId": "",

    "pricePerPart": 20000,

    "successPartCount": 1,

    "successT": "2019-07-01T05:31:23.187897Z",

    "message": "Test",

    "deliveredToVendor": true,

    "deliveredByVendor": true,

    "firstName": "",

    "lastName": "",

    "fullPhoneNumber": ""

}

“deliveredToVendor” indicates whether we have successfully sent the SMS to the respective telecom (mobile network operator).

“deliveredByVendor” means that the telecom provider (mobile network operator) reported to us – via a delivery receipt – whether it successfully delivered the SMS to the handset (i.e., the recipient’s phone).

Note: Delivery receipts from mobile network operators are not always reliable; it varies by country.

Have questions or need a little extra help?

Get in touch with us via:

Or drop us a message here: