Developers
- Home
- Developers
We use cookies
We use cookies to make your browsing experience on this website better.
https://api.bulksmsonline.co/smsapi?username=XXXX&password=YYYYY&type=Y&to=0000000000&source=sender&message=YourText
All parameters are explained below. Note that all the parameters, especially message and URL should be URL-UTF-8 encoded.
| Presence | Parameter | Description |
|---|---|---|
| Mandatory | username | The username of your account. |
| Mandatory | password | The password of your account. |
| Mandatory | type |
Message type to indicate if the message is text, Unicode, flash etc
t : Message to be sent as English/Latin language, Must be URL encoded (GSM 3.38 Character encoding). tf : Flash (GSM 3.38 Character encoding). u : Unicode messages such as Chinese or Arabic. uf: Unicode Flash messages such as Chinese or Arabic. |
| Mandatory | to | One or more phone numbers, separated by comma, max 30 number per request. |
| Mandatory | source |
The sender name that should appear from. • Max Length 18 numeric. • Max Length 11 alphanumeric. Additional restrictions on this field may be enforced by the SMSC. |
| Mandatory | message | The body of the SMS message. Sending Unicode messages such as Chinese or Arabic, needs to have the text encoded in UTF-16BE. |
| Optional | scheduled |
To schedule the message to be sent sometime/date in the future.
Time/Date format is: “yyyy-mm-dd hh:mm:ss” which must be URL encoded. - The time must be in UTC-04:00. via API (scheduled=2020-01-13T12:49:00). |
| Sr.No. | Error Code | Description |
|---|---|---|
| 1 | OK | MESSAGE ID | Success, Message Submitted Successfully. In this case you will receive the response OK|<MESSAGE ID>. The message Id can then be used later to map the delivery reports to this message. |
| 2 | E0002 | Invalid URL. This means that one of the parameters was not provided or left blank. |
| 3 | E0003 | Invalid username or password parameter. |
| 4 | E0004 | Invalid type parameter. |
| 5 | E0005 | Invalid message. |
| 6 | E0006 | Invalid to number. |
| 7 | E0007 | Invalid source (Sender name). |
| 8 | E0008 | Authentication failed. |
| 9 | E0010 | Internal server error. |
| 10 | E0022 | Insufficient account balance. |
| 11 | E0033/Http Status 429 | If more than 30 SMS/Sec, API calls quota exceeded! maximum admitted 30 per 1s. |
| 12 | E0044 | Mobile network not supported. |
Along with the above error’s codes, standard SMPP v3.4 error codes may also be returned where applicable.
https://api.bulksmsonline.co/smsapi?username=XXXX&password=YYYYY&type=t&to=00000000&source=xxxxxxx&message=Test%20Message!!!
The following observations can be made in the above URL:
https://api.bulksmsonline.co/smsapi?username=XXXX&password=YYYYY&type=u&to=00000000&source=xxxxxxxx&message= 00620075006C006B0073006D0073006F006E006C0069006E0065
On calling the above link by replacing the username and password by your account credentials, you should get the SMS ‘Test Message!!!’ on the mobile number in the to field.
The message has to be encoded on the UTF-16BE format and the type parameter has to be set to 6 i.e. (type=u).
https://api.bulksmsonline.co/smsapi?username=XXXX&password=YYYYY&type=t&to=00000000&source=xxxxxxxx&message= TestMessage&Scheduled=2020-01-08T05:54:00
It is possible to schedule delivery of a message to be sent at a specified date and time in the future. This is done by using the scheduledatetime parameter in your request.Time/Date format is: “yyyy-mm-dd hh:mm:ss”
https://api.bulksmsonline.co/balance?username=XXXX&password=YYYYY
It is possible to get your account balance by calling the above endpoint [GET, POST]. You can call the end point 2 times in each 1 min, any higher requests will be rejected.
For our customers that require low level control of SMS messaging and lowest possible latency, we offer our Enhanced SMPP service
Therefore, you need to reach out to our support team to get your credentials whitelist to use this service. This document provides a reference for all features available to you via the SMPP interface for sending SMS. Most importantly, SMPP is the industry standard for sending SMS to Network providers and is our native protocol.
Telecommunications industry uses the Short Message Peer-to-Peer (SMPP) as a protocol for exchanging SMS messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).
The most commonly use versions of SMPP are v3.3. Moreover, the most widely supportive standard, and v3.4, which adds transceiver support (single connections that can send and receive messages).
Subsequently, data exchange may be synchronous, where each peer must wait for a response for each PDU being sent.
SMPP account details
| Host | smpp.bulksmsonline.com |
|---|---|
| Port | 8889 |
| Username | Username |
| Password | \ |
Default 2 per SMPP account. For more connections, please contact your account manager.
To access our SMPP server the client IP range announcement and addition is must to our Firewalls. Therefore, please contact our support.
| SMPP PDU types |
|---|
| bind_transmitter / bind_transmitter_resp |
| bind_receiver/ bind_receiver_resp |
| bind_transceiver / bind_transceiver_resp |
| enquire_link / enquire_link _resp |
| unbind / unbind_resp |
| submit_sm / submit_sm_resp |
| data_sm / data_sm_resp |
| deliver_sm / deliver_sm_resp |
| generic_nack |
| query_sm / query_sm_resp |
| cancel_sm / cancel_sm_resp |
| replace_sm / replace_sm_resp |
Defination of the Type of source address by the source address TON and NPI parameters.
Moreover, the alphanumeric sender has limit and a maximum length of 11 characters
MSISDN sender maximum length is 18
In GSM, MSISDN is built up as:
| MSISDN | CC + NDC + SN |
|---|---|
| CC | Country Code |
| NDC | National Destination Code |
| SN | Subscriber Number |
Throughput and throttling:
Throughput is the maximum number of MT messages per second that can be sent from the SMPP account to our servers Default value is 10 per bind. So, to increase the value, contact your account manager.
Certainly, the recommended default window size (maximum open requests) is 5.
In short, the restriction of the throughput by the capacity of the operator receiving the MT messages.
Our recommendation is to set your enquire_link requests to 60 seconds.
Bulksmsonline SMSC uses UTC (Universal Time Coordination)
Submission Types:
Submission of messages may with either submit_sm or data_sm, using either the
short_message or message_payload fields.
The message length may not exceed the
byte limit for the network that the message is
being sent to (for example 140 byteson GSM networks).
Support of concatenated messages by using the User Data Header (UDH), which include in the message size byte limit.
A positive response to a ‘submit’ will contain an error code of zero and a non-null message reference.
A negative response will contain a vendor specific error code.
| Hex Value | Decimal | Description |
|---|---|---|
| 0x000000C5-0x000000FD | ||
| 0x00000000 | 0 | No Error |
| 0x00000001 | 1 | Message length is invalid |
| 0x00000002 | 2 | Command length is invalid |
| 0x00000003 | 3 | Invalid Command ID |
| 0x00000004 | 4 | Incorrect BIND Status for given command |
| 0x00000005 | 5 | ESME Already in Bound State |
| 0x00000006 | 6 | Invalid Priority Flag |
| 0x00000007 | 7 | Invalid Registered Delivery Flag |
| 0x00000008 | 8 | System Error |
| 0x00000009 | Reserved | |
| 0x0000000A | 10 | Invalid Source Address |
| 0x0000000B | 11 | Invalid Dest Addr |
| 0x0000000C | 12 | Message ID is invalid |
| 0x0000000D | 13 | Bind Failed |
| 0x0000000E | 14 | Invalid Password |
| 0x0000000F | 15 | Invalid System ID |
| 0x00000010 | 16 | Reserved |
| 0x00000011 | 17 | Cancel SM Failed |
| 0x00000012 | Reserved | |
| 0x00000013 | 19 | Replace SM Failed |
| 0x00000014 | 20 | Message Queue Full |
| 0x00000015 | 21 | Invalid Service Type |
| 0x00000016 | Reserved thru -0x00000032 | |
| 0x00000033 | 51 | Invalid number of destinations |
| 0x00000034 | 52 | Invalid Distribution List name |
| 0x00000035 | 53 | Reserved thru -0x0000003F |
| 0x00000040 | 64 | Destination flag is invalid (submit_multi) |
| 0x00000041 | Reserved | |
| 0x00000042 | 66 | Invalid submit with replace request; submit_sm with replace_if_present_flag set |
| 0x00000043 | 67 | Invalid esm_class field data |
| 0x00000044 | 68 | Cannot Submit to Distribution List |
| 0x00000045 | 69 | submit_sm or submit_multi failed |
| 0x00000046 | Reserved thru -0x00000047 | |
| 0x00000048 | 72 | Invalid Source address TON |
| 0x00000049 | 73 | Invalid Source address NPI |
| 0x00000050 | 80 | Invalid Destination address TON |
| 0x00000051 | 81 | Invalid Destination address NPI |
| 0x00000052 | Reserved | |
| 0x00000053 | 83 | Invalid system_type field |
| 0x00000054 | 84 | Invalid replace_if_present flag. |
| 0x00000055 | 85 | Invalid number of messages |
| 0x00000056 | Reserved thru -0x00000057 | |
| 0x00000058 | 88 | Throttling error; ESME has exceeded allowed message limits. |
| 0x00000059 | 89 | Reserved thru -0x00000060 |
| 0x00000061 | 97 | Invalid Scheduled Delivery Time |
| 0x00000062 | 98 | Invalid message validity period (Expiry time). |
| 0x00000063 | 99 | Predefined Message Invalid or Not Found |
| 0x00000064 | 100 | ESME Receiver Temporary App Error Code |
| 0x00000065 | 101 | ESME Receiver Permanent App Error Code |
| 0x00000066 | 102 | ESME Receiver Reject Message Error Code |
| 0x00000067 | 103 | query_sm request failed |
| 0x00000068 | 104 | Reserved thru -0x000000BF |
| 0x000000C0 | 192 | Error in the optional part of the PDU Body |
| 0x000000C1 | 193 | Optional Parameter not allowed |
| 0x000000C2 | 194 | Invalid Parameter Length |
| 0x000000C3 | 195 | Expected Optional Parameter missing. |
| 0x000000C4 | 196 | Invalid Optional Parameter Value |
| 0x000000FE | 245 | Delivery Failure, used for data_sm_resp |
| 0x000000FF | 255 | Unknown Error |
| 0x00000100 | Reserved for SMPP extension thru -0x000003FF |
Our SMPP will return a delivery report (Intermediate and/or final depending on the route the client will have to connect to SMPP server in the receiver or transceiver mode.
| Status | Description |
|---|---|
| DELIVRD | Message delivered to handset |
| FAILED | Message could not be delivered |
| EXPIRED | Message validity period expired, before any successful tries of submission |
| UNDELIV | Message is Undeliverable |
| REJECTD | Message REJECTD |
The most feature and rich API that bulksmsonline.co offers is the SMS REST API. Single messages, scheduled batch send-outs, using message templates and more.
RESTful API is ideal for the programmatic sending of SMS, regardless of volume. Developers wanting a more extensive integration solution will find that this API perfectly caters to their programmatic sending needs. The API is designed using RESTful standards over HTTP and accepts JSON data.
Required Knowledge
If you plan on using the API you should be familiar with the following:
The base URL for the API is:
https://api.bulksmsonline.co
The base URL supports HTTPS. To access a specific version of the API, simply postfix the URL with the version of the API, as in the case of:
https://api.bulksmsonline.co/rest/api/v1
The base URL will always be set to use the latest version of the API. However, in order to reduce the chance of compatibility issues, always reference the version you are developing against in the URL.
To use the API you must use your account username and password to generate a temporary token (See Authentication Tokens) and include the token in HTTP requests. This mechanism minimises the risk of compromising your API credentials.
With the prerequisites completed, you can now start using the API. The following sections of this guide will briefly explain the available features of the REST API.
For technical details about the HTTP request and response objects for each function, please refer to the following documentation.
The REST Messaging API is designed to be a simple and powerful tool for large scale messaging with features such as:
To use the REST API you first need to create an HTTP REST Token. You can have multiple service tokens and each one will see their messages, groups or other resources isolated from each other.
You will be provided with an authentication token for each service request.
The token is sent in the Authorization header preceded by Bearer. It is required for all requests made to the REST API.
https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/YourUsername/password/YourPassword
Base URL to send sms
The following URLs can be used by the REST API. We have servers in the US and Singapore.
https://api.bulksmsonline.co/rest/api/v1/sms/send/
The rate limit is calculated from all messages sent via the API, so a batch with 15 recipients will count as 15 messages for rate limiting purposes.
This means that new batches will be accepted immediately but might be delayed if earlier batches are still on queue.
This section will take a brief look at some of the formats used in the REST API.
JSON
JSON (application/json) is the content type of both requests and responses if not otherwise specified. Requests with invalid JSON will be rejected.
Null values can be omitted in requests and will be omitted in responses. In some cases explicitly setting null will overwrite a previously set value with null. See Update a group for an example.
MSISDN
Only MSISDNs in international format are accepted by the API..
MSISDNs can be sent in with or without a leading + (i.e. +123456789 or 123456789) and
without a leading 00.
Any space, dash or bracket will also be ignored by the API.
All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were sent in with one.
{
from string
nullable: true
to [
nullable: true
string]
type stringEnum:
[ Text, FlashText, UniCode, UniCodeFlash ]
content string
nullable: true
sendDateTime string($date-time)
nullable: true
}
The following HTTP status codes are used by the API. Additional codes might be added in the future and if you encounter a code not in this list please consult the HTTP specification for a definition.
| Status | Description |
|---|---|
| 200 OK | Success - Returns the newly created token |
| 401 Unauthorized | Unauthorized - If the credentials provided are wrong |
| 402 Payment Required | Payment Required - If the account has 0 balance or expired |
| 402 Payment Required | Forbidden - If the request has invalid actions |
| 404 Not Found | Invalid path |
| 405 | Method Not Allowed |
| 500 Internal Server Error | Internal Server Error |
| 503 Service Unavailable | Service Unavailable |
The following codes can be returned as values for the code field:
| HTTP Status | Code | Description |
|---|---|---|
| 200 | Success | Sent SMS |
| 400 | Bad Request | Invalid Parameters |
| 401 | Unauthorized | Invalid Token |
| 404 | Not Found | invalid path |
| 405 | - | Method Not Allowed |
| 500 | - | Internal Server Error |
| 503 | - | Service Unavailable |
https://api.bulksmsonline.co/mnv?username=XXXX&password=YYYYY&msisdn=12345677899
You can use Number Validation API to retrieve validity information for a phone number. Number Validation API is a synchronous, easy-to-use web service. As any phone number is concerned, you can:
Designed for companies with vast number of database records, our Database Cleaning package enables identifying unused and inactive numbers.
Our MNV service differentiates between landline and mobile phone numbers. This, in turn, helps you send SMS to the apt line type and consequently saves your valuable resources and time for your business.
https://api.bulksmsonline.co/mnp?username=XXXX&password=YYYYY&msisdn=12345677899
Performing a Number Lookup provides a direct network level check against any GSM mobile number. The check can provide detailed information, such as the original network a mobile number was assigned, whether the number has been ported to a different network, which ported network it has moved to, if the mobile has been turned on recently and the country the mobile was last used.
Mobile subscribers often change numbers, roaming or change providers while retaining their original phone number (ported numbers). Knowing which mobile numbers are in use and available, or which network your client is currently using, can greatly improve accuracy and cost effectiveness for many types of businesses..
With Number Lookup, you can determine:
Designed for companies with vast number of database records, our Database Cleaning package enables identifying unused and inactive numbers.
Roaming information is used to optimize phone call routing and termination, and minimise telecom costs.
Financial institutions (BFI) using the service, for roaming (location) information in order to prevent ATM frauds and much more.
Search the home network of your current customers and direct your calls consequently.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''
' :: How to generate Token in C# using our Restful API
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''
var client = new RestClient(" https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/YOURUSERNAME/password/YOURPASSWORD");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''
' ::: How to send sms with your generated Token
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ''''''''
var client = new RestClient(" https://api.bulksmsonline.co/rest/api/v1/sms/send");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("token", "USER TOKEN GENERATED FROM GET TOKEN API");
request.AddParameter(
"application/json",
"{\"from\":\"Sender Name\",\"to\":[\"16813000014\",\"16813000014\"],\"type\":\"Text\",\"content\":\"Sample SMS Content To Be Sent\"}",
ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
/*
*:: How to generate Token in PHP using our Restful API
*/
" https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/YOURUSERNAME/password/YOURPASSWORD",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
/*
*::: How to send sms with your generated Token
*/
" https://api.bulksmsonline.co/rest/api/sms/send",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"from\":\"Sender Name\",\"to\":[\"16813000014\",\"16813000014\"],\"type\":\"Text\",\"content\":\"Sample SMS Content To Be Sent\"}",
CURLOPT_HTTPHEADER => array(
"token : USER TOKEN GENERATED FROM GET TOKEN API",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
/**
* :: How to generate Token in JAVA using our Restful API
**/
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url(" https://api.bulksmsonline.co/rest/api/v1/sms/gettoken/username/YOURUSERNAME/password/YOURPASSWORD")
.get()
.build();
Response response = client.newCall(request).execute();
/**
* ::: How to send sms with your generated Token
**/
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(
mediaType,
"{\"from\":\"Sender Name\",\"to\":[\"16813000014\",\"16813000014\"],\"type\":\"Text\",\"content\":\"Sample SMS Content To Be Sent\"}"
);
Request request = new Request.Builder()
.url(" https://api.bulksmsonline.co/rest/api/v1/sms/send")
.post(body)
.addHeader("token", "USER TOKEN GENERATED FROM GET TOKEN API")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
Expand your business today!
Try It Now For Free