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://app.engagespark.com/account/profile/info).
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://app.engagespark.com/account/organization/info). | 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 delivery deadline 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?