API Reference
With our REST, easy, and smart “SMS” APIs we allow you to integrate SMS at your app and get started in seconds, With Taqnyat, building a solution with SMS capabilities never been easier, a few lines of code will enable the SMS to create a magnificent app fit with your business needs.
In the below guide, we'll walk you through and explain how Taqnyat SMS API work:
APIs Features:
Connecting to taqnyat.sa API is simple & easy, you can do it using HTML forms, which will send the data as POST, or send data to API URL directly using Query String, which will send the data as "GET". If you want to send a large amount of data, we recommend that you use the first method, which is POST; because the second method GET does not support sending a large amount of data. Besides, you can send data in JSON, a full description of the JSON Data method will be in this document.
taqnyat.sa also returns the data in the most common format, which is JSON.
When you connect to taqnyat.sa API through HTTP/HTTPS protocols, the SMS data must be in a certain format as follows: Sender Name must be encoded using URL-Encoding and message text must be in UTF-8 encodings:
Before you go
- We recommended the one who is going to use this documentation or APIs to have programming skills.
- The testing cost is nothing because we offer a free startup balance of 1 SAR for any trial account.
- Cost calculation for messaging depends on how many messages you will send and how many destinations it will be receiving the messages.
- If you want to try to send SMS API, we advise you to send scheduled SMS, so you can check if they reached “Scheduled SMS Archive” in your taqnyat.sa account, then you may delete the SMS to spare the cost and get your balance back. When you send SMS through API, mobile numbers that will receive the SMS must be in international format without 00 or symbol (+)
- You must have an active sender name before you go, you may contact support@taqnyat.sa or account manager to get more details about the requirements and how to activate your Sender Name.
Base URL
https://api.taqnyat.sa/
Authentication
To use our API, you will need a unique Bearer token generated from your account at our platform by following the below steps Setup Bearer token
For REST API Bearer token must be submitted withen the header Authorization.
Setup Bearer token
With Taqnyat you can set up your bearer token in seconds using the below steps:
- Login to your account at Taqnyat.
- Select Application from Developer section.
- Press the add button on the top right corner.
- Choose a suitable name for your application.
- Select the services you want this app to include , in our case SMS.
- Hit the confirm button to submit your application.
- Copy the Bearer Tokens.
Let us Get started:
To use taqnyat.sa API, you should have a taqnyat.sa account, here is an explanation of how you can register, checking your current balance, request a recharge for your balance through a “request recharge form” in taqnyat.sa website.
-
Registration process: You can register on taqnyat.sa website through the following link: Contact and go to Sales tab ,fill the form and hit send.
-
Check your balance: You can check your current balance from the website after you logged at the dashboard.
-
Balance Topup: After your login to your https://www.taqnyat.sa account, you can request recharging your balance, through the request top-up form, you can access it through the balance top-up tab located in the left top corner. Fill all the required data in the form and we will top up your account within two hours at most after we validate the deposit.
-
Using bearer Tokens: bearer Tokens will have a unique value generated in the taqnyat.sa user account , because it provides a more secure connection with the API.
-
Setup API settings: taqnyat.sa provides security settings that allows you to control SMS sending through API. You can enable or disable sending SMS through API from your account, grant permission to specific IP’s to be allowed to send SMS message through API using your account, and grant permission to specific countries to be allowed to send SMS message through API using your account.
System
System resources are used to retrieve info about the system.
System status
This method used to retrieve status for one or multiple services in the system. Authorization is not required .
Here are some examples of HTTP API:
https://api.taqnyat.sa/system/status
if the request submitted successfully header status of 200 will be return as follows:
{
statusCode: 200,
status: {
service: "none",
description: "All Services are Operational"
}
}
if the request return header 405 , you are using RESTFull API and have used unauthorized method for example if the System resource allow only get , and you used post error 405 expected to return.
{
"statusCode": 405,
"message": "Method Not Allowed"
}
Send a Mail
| Parameter | Description | Required |
|---|---|---|
| campaignName | The Name of Your Campain | Yes |
| subject | The Subject for your Email | Yes |
| from | The Sender Email | Yes |
| to | Array of Resivers Email | Yes |
| msg | The Message that you want to send it | Yes |
Here is some example of HTTP API to send text:
https://api.taqnyat.sa/mailSend.php?
bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
campaignName=your campain name&
subject= youe email subject&
from=mail@example.com&
to=mail1@example.com,mail2@example.com&
msg=your message text
Here is some example of HTTP API to send HTML code:
https://api.taqnyat.sa/mailSend.php?
bearerTokens=xxxxxxxxxxxxxxxxxxxxxxxxxx&
campaignName=your campain name&
subject= youe email subject&
from=mail@example.com&
to=mail1@example.com,mail2@example.com&
msg=<html><body><b>test</b></body></html>
if the request submitted successfully header status of 201 will be return as follows:
{
"status": 1,
"ResponseStatus":"success",
"Data": {
"msgId":202,
"result":1,
"MessageAr":"تم الإرسال",
"MessageEn":"sent successfully",
"price":"0",
}
"Error":null,
}
if the request return ErrorCode 2
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":2,
"MessageAr":" الرصيد = 0",
"MessageEn":" Your balance is 0"",
}
}
if the request return ErrorCode 3
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":2,
"MessageAr":" الرصيد غير كافي",
"MessageEn":" Your balance is not enough"",
}
}
if the request return ErrorCode 14
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":14,
"MessageAr":" خطا في المرسل",
"MessageEn":" error From"",
}
}
if the request return ErrorCode 15
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":15,
"MessageAr":" البريد الالكتروني المرسل لها غير صحيحه أو فارغه",
"MessageEn":" Email is not specified or incorrect"",
}
}
if the request return ErrorCode 16
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":16,
"MessageAr":" يوجد خطا في عنوان الرساله",
"MessageEn":" error subject"",
}
}
if the request return ErrorCode 17
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":17,
"MessageAr":" يوجد خطا في الرساله",
"MessageEn":" error msg"",
}
}
if the request return ErrorCode 101
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":101,
"MessageAr":" الارسال باستخدام بوابات الارسال معطل",
"MessageEn":"Invalid Bearer Tokens",
}
}
if the request return ErrorCode 102
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":102,
"MessageAr":" هذا الاي بي 10.0.0.1 غير مصرح له باستخدم بوابات الارسال",
"MessageEn":" this ip 10.0.0.1 Not authorized to using the API"",
}
}
if the request return ErrorCode 104 , you are using wrong bearer Tokens make sure to follow the steps in above to setup your bearer Token Setup Bearer token
{
"status": 1,
"ResponseStatus":"fail",
"Data":null,
"Error": {
"ErrorCode":104,
"MessageAr":" مفتاح الارسال غير صحيح",
"MessageEn":"Invalid Bearer Tokens",
}
}
Mail Error codes
Below on the table list for code in the response , if the header returned 400 . lookup the code of the response with code on the table for better understanding the error cause.
| number | Error | Description |
|---|---|---|
| 2 | Your balance is 0 | Your balance has been consumed and you need to top up your account to restore the ability to send mail again. |
| 3 | Your balance is not enough | Your account has a low balance and does not cover all mail you are about to send. |
| 14 | error From | Sender email used is not correct, make sure to include the sender email with correct format |
| 15 | Email is not specified or incorrect | Resivers Emails used is not correct, make sure to include the Resivers Emails as Array of emails with correct format |
| 16 | error subject | subject used is not correct, make sure to include the subject as text |
| 17 | error msg | message used is not correct, make sure to include the message as text |
| 101 | sending by API is disabled | the functionality or capability to send data or requests through an API has been deactivated or turned off |
| 102 | this ip 10.0.0.1 Not authorized to using the API | the IP address from which you are attempting to access an API service is not granted permission or authorization to do so. |
| 104 | Invalid Bearer Tokens | the API key you are using to authenticate or authorize your access to the API service is either missing, incorrect, expired, or revoked. |