kwtSMS

API Documentation

HTTP/REST (JSON)/SMTP

2024/01/25 - v3.7

kwtSMS.com API Documentation v3.7 P a g e 1 of 15

 Table of Contents

1. Requirements
2. Register Account
3. Features
4. HTTP API
a. balance
b. senderid
c. dlr
d. send
5. REST API
a. balance
b. senderid
c. dlr
d. send
6. SMTP API
7. Error Codes
8. Implementation Best Practices
9. FAQs
10. Sample Code
a. PHP
b. Python
c. NODE.js
11. Change Log

IMPORTANT SECURITY CONSIDERATIONS

Always use SSL (https) enabled links or URLs

SSL will encrypt your traffic and protect you from eavesdropping and information stealing.

Always use HTTP POST method never use GET

When you use HTTP GET method, all your data including usernames and passwords are
logged by the server in clear text even if you use SSL.

Do not hardcode usernames and passwords into the code

Allow the client the freedom and ease to change his/her password anytime they wish.
Especially important in case of the password compromised.

kwtSMS.com API Documentation v3.7 P a g e 2 of 15

Requirements for kwtSMS API:
1. You must have internet connection to connect to our website/software/app.
2. You must have an active account in kwtSMS.com.
3. Your kwtSMS.com account must be setup to use the API, after setup you will
find API username and password in your kwtSMS account.
4. You can change API Password from your kwtSMS account after login.

API Use
You need username and password for API calls
Do not use your mobile number as username, it will not work!
You can find it in your kwtSMS.com account API page, after it is enabled

New Account Registration:

1. Goto our website: www.kwtsms.com
2. Click on Signup or Register
3. Activate your account with OTP message (if you did not get the activation
message contact us)
4. Request API functionality from your account API menu.
5. We will get your account ready ASAP and send you confirmation. Then you
can start testing and integration with your website/software/app.
6. For support and help contact us using one of the methods on our website
(eMail,whatsapp,phone)

kwtSMS API Features:

1. Send messages to Kuwait (Zain, Ooredoo, STC, Virgin) or outside Kuwait.
2. The ability to send up to 200 numbers at a time.
3. Send in English or Arabic (Windows or UTF8 encoding) or in Unicode. No
need for conversion.
4. All messages will be logged in your KwtSMS.com account for reporting.
5. You can check your account balance and available sender-ids.
6. You can pull delivery reports of your sent messages when they are available.
7. You can send long messages up to 6 pages in length.
(1 Arabic message = 70 characters. 1 English message = 160 characters)
8. You should always use SSL encryption for security and privacy (HTTPS).
9. API lockdown feature. API will only accept requests from whitelisted IP
addresses. This adds extra layer of security for your API.
10. API error log in account page, to easily troubleshoot integration issues.

kwtSMS.com API Documentation v3.7 P a g e 3 of 15

 HTTP API

IMPORTANT NOTE

HTTP Headers for Content-Type and Accept must be set to: text/html
HTTP Method: POST

Balance command:
This command is used to retrieve the account balance and total purchased credits.

URL: https://www.kwtsms.com/API/balance/

Balance parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API Username
password Alphanumeric 30 Yes API password

Sample output:
181.00/1000.00

[Current Balance / Total Purchased Credits]

Senderid command:
This command is used to retrieve all available senderids that can be used in the (send) command.

URL: https://www.kwtsms.com/API/senderid/

Senderid parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API Username
password Alphanumeric 30 Yes API password

Sample output:
KWT-SMS
KWT-TEST

kwtSMS.com API Documentation v3.7 P a g e 4 of 15

DLR command:
This command is for retrieving the delivery reports for an already sent message.

URL: https://www.kwtsms.com/API/dlr/

DLR parameters:
Variable Type Max Mandatory Description
username Alphanumeric 15 Yes API username
password Alphanumeric 30 Yes API password
msgid Alphanumeric 32 Yes This is a unique msgid that was generated
previously by the API when you sent the
message. So, if you want to check for delivery
reports you must save the message id in your
database.

Sample: output:
xxxxxxxx,Blacklisted
xxxxxxxx,Delivered to mobile

Send command:
This command is used to send SMS messages.

URL: https://www.kwtsms.com/API/send/

Send parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API username
password Alphanumeric 30 Yes API password
sender Alphanumeric 11 Yes Use your private senderid or one of ours.
SenderID is case sensitive.
mobile Numeric 2500 Yes ',' comma separated, no '+' or '00' or '.' or
space in numbers, English only (1,2,3,..)
lang Numeric 1 Yes 1: English (ASCII)
2: Arabic (CP1256)
3: Arabic (UTF-8)
4: Unicode
test Numeric 1 No 1 or 0: If set, messages will not be sent to
handsets, but will be inserted to the queue
and can be deleted to recover the credits.
message Alphanumeric - Yes use “\n” for new lines, no html or emoji

Sample output:
OK:f4c841adee210f31307633ceaebff2ec:1:1:180:1242667894

Field list in order separate by colon:

RESULT:MSG-ID:NUMBERS:POINTS-CHARGED:BALANCE-AFTER:UNIX-TIMESTAMP

kwtSMS.com API Documentation v3.7 P a g e 5 of 15

 REST/JSON API

IMPORTANT NOTE

HTTP Headers for Content-Type or Accept must be set to: application/json

HTTP Method: POST

Balance command:
This command is used to retrieve the account balance and total purchased credits.

URL: https://www.kwtsms.com/API/balance/

Balance parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API Username
password Alphanumeric 30 Yes API password

Sample input payload:

{“username”:”myuser”, “password”:”mypass” }

Sample output:
{"result":"OK","available":150,"purchased":1000}

Senderid command:
This command is used to retrieve all available senderids that can be used in the (send) command.

URL: https://www.kwtsms.com/API/senderid/

Senderid parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API Username
password Alphanumeric 30 Yes API password

Sample input payload:

{“username”:”myuser”, “password”:”mypass” }

Sample output:
{"result":"OK","senderid":[“KWT-SMS","KWT-TEST"]}

Sample JSON Error output:

{"result": "ERROR", "code": "ERR003", "description": "Authentication error, username or password
are not correct."}

kwtSMS.com API Documentation v3.7 P a g e 6 of 15

 DLR command:
This command is for retrieving the delivery reports for an already sent message.

URL: https://www.kwtsms.com/API/dlr/

DLR parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API username
password Alphanumeric 30 Yes API password
msgid Alphanumeric 32 Yes This is a unique msgid that was generated
previously by the API when you sent the
message. So, if you want to check for delivery
reports you must save the message id in your
database.

Sample input payload:

{“username”:”myuser”, “password”:”mypass”, “msgid”:’xxxxxxxxxxxxxxxxxxxxxxxx’ }

Sample: output:
{"result":"OK","report":[{"Number":"xxxxxxxx","Status":"Received by recipient"}]}

Send command:
This command is used to send SMS messages.

URL: https://www.kwtsms.com/API/send/

Send parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API username
password Alphanumeric 30 Yes API password
sender Alphanumeric 11 Yes Use your private senderid or one of ours.
SenderID is case sensitive.
mobile Numeric 2500 Yes ',' comma separated, no '+' or '00' or '.' or
space in numbers, English only (1,2,3,..)
lang Numeric 1 Yes 1: English
2: Arabic (CP1256)
3: Arabic (UTF-8)
4: Unicode
test Numeric 1 No 1 or 0: If set, messages will not be sent to
handsets, but will be inserted to the queue
and can be deleted to recover the credits.
message Alphanumeric - Yes use “\n” for new lines, no html or emoji

Sample input payload:

{ “username”:”myuser”, “password”:”mypass”, “test”:”1”, “sender”:”KWT-SMS”,
“mobile”:”96599220322,96599220322”, “lang”:”2”, “message”:”‫ تجربة‬+‫} ”عربي‬

Sample output:
{"result":"OK","msg-id":"f4c841adee210f31307633ceaebff2ec","numbers":1,"points-
charged":1,"balance-after":180,"unix-timestamp":1684763355}

kwtSMS.com API Documentation v3.7 P a g e 7 of 15

 SMTP API
We encourage using the normal HTTP API to send SMS but in some scenarios and implementations,
servers do not have direct internet access, so this is helpful to send SMS for computers behind
firewall or closed network.

Needless to say, using this method is very insecure as emails travel though the internet in plain
text and not encrypted.

Send email to: [email protected]

The email content type should be Text, and not Rich text or HTML.

eMail Parameters:
Variable Type #Chrs Mandatory Description
username Alphanumeric 15 Yes API username
password Alphanumeric 30 Yes API password
sender Alphanumeric 11 Yes Use your private senderid or one of ours.
SenderID is case sensitive.
mobile Numeric 2500 Yes ',' comma separated, no '+' or '00' or '.' or
space in numbers
lang Numeric 1 Yes 1: English
2: Arabic (CP1256)
3: Arabic (UTF-8)
4: Unicode
message Alphanumeric - Yes use “\n” for new lines

eMail body sample:

username:xx2xxx
password:xx3xxx
sender:SenderID
mobile:96597119220,96566074414
lang:1
text:Meet me at Starbucks!

The email subject is ignored. The parameter value should be in the same line.

NOTE: If there is anything wrong with your email or parameters or balance your message will not
be sent and you will not get error message.

kwtSMS.com API Documentation v3.7 P a g e 8 of 15

 Error Codes
Code Function Description
ERR001 ALL API off
ERR002 ALL Username or Password or other required parameters are missing
ERR003 ALL Wrong username or password
ERR004 ALL Your account does not have API access
ERR005 ALL Your account has been blocked
ERR006 send No valid numbers submitted
ERR007 send Cannot send more than 200 numbers at a time
ERR008 send The senderid chosen is banned
ERR009 send Message parameter is empty
ERR010 send Your account balance is zero
ERR011 send Not enough balance to send this message
ERR012 send Cannot send more than 6 page messages, message is too long
ERR013 send Your queued messages reached 500, wait and try again
ERR019 dlr No reports found
ERR020 dlr Message does not exist
ERR021 dlr message does not have delivery report
ERR022 dlr Delivery reports are not ready. Check back after 24 hours
ERR023 dlr Unknown error Could not get delivery reports
ERR024 ALL API Lockdown is ON and IP address not in the allowed list
ERR025 send No valid numbers found, cannot send the message
ERR026 send No route found for this number, network not supported, contact us
to add destination network
ERR027 send HTML tags not allowed

kwtSMS.com API Documentation v3.7 P a g e 9 of 15

 Implementation Best Practices

1. Always use HTTPS and POST method for security

SSL will encrypt your traffic and protect you from eavesdropping and information stealing.
When you use HTTP GET method, all your data including usernames and passwords are logged by
the server in clear text even if you use SSL. Avoid adding user/pass in URLs like this:
https://www.kwtsms.com/ API/send/?username=XXX&password=XXX <= Don’t do this.

2. Do not hard code the username/password into your code

Allow the client the freedom and ease to change his/her password anytime they wish. Especially
important in case of the password compromised. Add settings variables to your app.

3. Test sending messages in English and Arabic before handoff

Test sending in both languages in case the client tries to use one of them. Otherwise, the message
will be unreadable (gibberish).

4. When sending OTP include the app name in the messages

To comply with telecom rules, OTP and critical notifications must include the application/company
name for security reasons. Example: Your OTP for APPNAME is: 12345

5. When sending OTP allow 3 minutes before SMS resend

First, make sure you are using Transactional Private SenderID for faster OTP delivery. Give the
user room to receive and find the SMS, then copy paste the code. Not all users are computer
wizards. Official KNET payment gateway allows 4 minutes before expiration.

6. User input sanitization, especially mobile numbers

Make sure the mobile numbers are correctly formatted and in international format, remove + or
00 and add country code if the user did not. Otherwise, the API will not accept your message.
Numbers must be in English (1,2,3,..). Arabic/Hindi numbers will not be accepted.
Clean your text messages from emojis and special characters. Otherwise, it will get stuck in the
queue and will not be sent.

7. No need to call /balance/ function after each send

When you do successful send, the API already returns how many points charged and the balance
after sending. We also have low balance notifications for each API account.

kwtSMS.com API Documentation v3.7 P a g e 10 of 15

 Frequently Asked Questions – FAQs
I always get this error “Username or password is wrong” even though I am sure
I enter the correct username/password?!
This happens if you are using GET request and your password contains special characters like # or & or ? . To fix
this, change the request method from GET to POST or change your password. Always use HTTPS in both
methods. Also, make sure that your username is not your account/mobile number.

How to add new lines in text messages?

Try using “\n” for new lines.

Why sending messages in Arabic, I receive weird symbols/codes?

Try changing the “lang” variable until it is fixed.

I sent a message credits deducted and message not received!?

Please follow the steps below before you contact us:
1. Check the Sending Queue, your message could be stock for some reason, delete it and your
account will be credited back.
2. Did you remember to set the variable test=0 ?
3. Check the Archive, if your message is NOT in the Archive that means you did not send it.
4. Check the numbers, open the message from the Archive and make sure the numbers are in
the list and correct.
5. Note that some numbers can be blacklisted/filtered by the owner request.
6. Rarely, a delay happens due to marketing campaigns or busy seasons.
7. If the number is in DND list (blacklist) and you are using promotional senderid, your
message will be filtered (not delivered).
8. Still need help? contact us with the following information: Name, Account, MessageID,
Time&Date of message, Message Text.

When I send a message the senderid is always KWT-SMS, why?

This is the default test/promotional senderid. The system will use it if you did not buy your own
private senderid. You must set your senderid exactly same case as it appears on your account. The
senderid is case sensitive. So Kuwait is NOT same as kuwait or KUWAIT.

Why delivery reports are not ready?

Delivery reports (DLR) usually take 24 hours to be updated. It is worth mentioning that after
Kuwait implemented mobile number portability (MNP) the delivery reports will not be accurate. So
they are not to be relied on to measure SMS campaign effectiveness or link open rate.

What is Blacklist number? and how to fix it?

Blacklists (DND list) are filters put by the telecom company to protect their customers from spam
and advertising. The owner of the number asks his telecom company to be on this list, then he will
not receive any messages unless from whitelisted SenderIDs. Only the owner of the number can
ask to be removed from the list by calling his telecom company.

How to Whitelist my SenderID for OTP?

If you send critical activation & notification messages and need them to be delivered to everyone
even Blacklisted numbers, then you must apply for whitelisting your SenderID. Prepare a request
with your company letterhead and send it to us, we will take care of the rest.

I cannot open your website it seems down?

Maybe our server is down (unlikely) OR you IP address was blocked automatically by our firewall.
Please contact us with your public IP address so we can check.

kwtSMS.com API Documentation v3.7 P a g e 11 of 15

 Sample Code
NOTE: we only use the POST method with SSL, for obvious security reasons.

1. PHP
<?php
// Set up API URL and parameters
$url = "https://www.kwtsms.com/API/balance/";
$username = "your_username";
$password = "your_password";
$params = array(
"username" => $username,
"password" => $password
);

// Set up cURL session

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

// Execute the request and handle any errors

$result = curl_exec($ch);
if (curl_errno($ch)) {
echo "Error: " . curl_error($ch);
} else {
echo $result;
}

// Close cURL session

curl_close($ch);
?>

Note that we are using cURL to make the HTTP request to the API. This is a common
method for making HTTP requests in PHP. Additionally, we are using SSL verification to
ensure that the API server's SSL certificate is valid and trusted. This is an important
security measure.

kwtSMS.com API Documentation v3.7 P a g e 12 of 15

 2. PYTHON
import requests

# Set up API URL and parameters

url = "https://www. kwtsms.com/API/balance/"
username = "your_username"
password = "your_password"
params = {
"username": username,
"password": password
}

# Execute the request and handle any errors

response = requests.post(url, data=params, verify=True)
if response.status_code != 200:
print("Error: HTTP status code ", response.status_code)
else:
print(response.text)

Note that We are using the requests library to make the HTTP request to the API. This is a
common method for making HTTP requests in Python. Additionally, we are using SSL
verification to ensure that the API server's SSL certificate is valid and trusted. This is an
important security measure.

kwtSMS.com API Documentation v3.7 P a g e 13 of 15

 3. NODE.js
const https = require('https');

const options = {
hostname: 'www.example.com',
port: 443,
path: '/api/balance/',
method: 'POST',
headers: {
'Content-Type': 'text/html'
}
};

const req = https.request(options, res => {

console.log(`statusCode: ${res.statusCode}`);

res.on('data', d => {
process.stdout.write(d);
});
});

req.on('error', error => {

console.error(error);
});

const postData = 'username=your_username&password=your_password';

req.write(postData);
req.end();

We are using the https module to make the HTTPS request to the API. We set up the
appropriate request options, including the URL and request method, and handle the
response accordingly. We also write the POST data to the request body before ending the
request.

More code samples can be found in your kwtSMS.com account.

https://www.kwtsms.com/account/api/code/

kwtSMS.com API Documentation v3.7 P a g e 14 of 15

 Change Log
Date Version Description
2009-09-06 1.0  First release

 Added (Table of contents) page and reformatted the whole

2020-10-15 2.0 document with tables
 Added error codes reference table/page

 Added (dlr) HTTP API command

2023-02-01 2.5  Added frequently asked questions (FAQ) page
 Added more error codes

 Added (Important Security Considerations)

 Added Sample Code pages (PHP,Python,NODE.js)
 Added this Change Log page
2023-04-01 3.0  Updated new Account section, now you can request the API directly
from the website.
 Updated API Features section, added couple of new features
 Update the FAQ page and revised some answers
 Added test variable to the sender command
2023-04-20 3.1
 Added two new error codes for the send API call
 Added JSON support to API
2023-05-22 3.5
 Removed all references to GET request. Use HTTP POST method only
 Fixed typos in JSON send variables
 Added “Implementation Best Practices” page
2023-12-18 3.6
 Added FAQ how to add new lines in text messages
 Added FAQ getting weird codes when sending in Arabic
 Updated kwtSMS API features
2024-01-25 3.7  Removed references to using + in messages
 Added new error code

kwtSMS.com API Documentation v3.7 P a g e 15 of 15