Bulk SMS messaging API specification

Introduction


Sendberry is a high-quality SMS platform which allows you to integrate any of your applications with our SMS message sending and receiving system. Simplicity of implementation is the main advantage of our system. All SMS messages may have your company name, personal phone number or any phone number you own as sender name. Every message sent from our system has its own unique ID which allows you to receive delivery confirmation.
The HTTP API allows you to integrate your application with Sendberry using the HTTP protocol in order to send SMS messages. The client’s application issues either HTTP GET or POST request to the Sendberry HTTP API interface supplying, therefore, a list of required parameters. Sendberry API issues back HTTP response indicating the validity of transaction.
All in all, the HTTP API server platform allows users to send messages. To gain access to individual statistics and invoices please visit https://app.sendberry.com using your own login details.

Before you start


Signing up for an account
To work with our APIs you will be needing to sign up for an account. Thereby you will be provided with an API key which means you will be able to set your own username and password and use those to access our APIs.
API activation
API HTTP requests are protected with authentication. You need to use your API authentication key, access name and access password for HTTP authentication with Sendberry. To set your name, password and key please log into your account using your login and password and go to API section. The key is generated automatically by the system and can not be set manually.

The API endpoint

The API is served over HTTPS. To ensure data privacy unencrypted HTTP is not supported.
Send single or bulk SMS, request delivery reports
https://api.sendberry.com/SMS

System status and information about available balance
https://api.sendberry.com/STATUS

Blacklist recipients and manage opt-out requests
https://api.sendberry.com/CONTACT

Sender ID

Sender ID indicates the creator and the dispatcher of SMS messages. According to the SMS standards, the length of Sender ID is limited to 15 digits if it is a number and to 11 characters if it is a text (alphanumeric Sender ID). You are able to use spaces when creating Sender ID but please be informed that most of modern smartphones do not display the space.
Alphanumeric Sender ID
Alphanumeric Sender ID allows you to send personalised text messages which do not need a reply. You can apply for Sender IDs that are directly connected to your business, for example: Taxi, ToyShop, Hotel. This is certainly the best solution for transactional SMS including order confirmations or temporary security codes. You can add as many Alphanumeric Sender ID as needed, each new Sender ID should be reviewed by our support team within 24 hours.
Your phone number
You can use your own mobile phone number as the Sender ID to get customers’ replies or callbacks. In order to validate new sender phone number we will provide you with a verification code.
Personal two-way number
If you need to maintain a two-way communication with your clients and receive clients’ responses you can use our Two-way SMS service. Customers’ replies may be received via manual API request, web hook or in inbox using Sendberry Portal. For some destinations there might be specific country or network restrictions regarding senders. Therefore, the alphanumeric sender ID might be automatically replaced or, otherwise, you might be needing to use a special sender ID for the appropriate destination or network.

SMS content and numbers format

The maximum size of one SMS message is 140 bytes. Consequently, messages larger than 140 bytes are chained together with the help of some of these bytes leaving 134 bytes for each message.
The use of GSM 03.38 extends the length of one SMS message to 7 bits per character instead of the ordinary 8 bits per character as with UTF-8. This means there are 160 characters available for one page. In case the message is longer than 160 characters 7 bits are used to chain the messages together. There are 153 characters per one message left in total.
By using UCS2 you will able to operate with a wide range of different characters that are not available in GSM 03.38. This is accomplished by using only 2 bytes per character whilst providing 70 characters for one message. In case the total amount of 70 characters is overpassed messages are chained together supplying 134 bytes or 67 characters per message.
GSM 03.38 (by default)
7 bits per character available. Accordingly, the length of a message is extended up to 140 bytes maximum. Messages longer than 160 characters are chained together meaning the length of one message being shortened to 153 characters.
UCS2
Enables the use of different special characters. 2 bytes per character (70 characters per message) available. Messages longer than 70 characters are chained together whilst 67 characters per message being le".
Recipient number format
You must use the E.164 phone number format when making an API request as no local phone formats are accepted (i.e. use 447700809657 instead of 077 0080 9657). This restriction has been applied to ensure the delivery to the desired number without any accidental local-to-international phone transformations.
Read more about SMS message content and SMS symbols.
Your string should be url-encoded.

Sending SMS

To send a new message make an HTTP POST or GET request to the SMS API address
https://api.sendberry.com/SMS/SEND

Outgoing messages
When creating a new message via API six mandatory parameters must be included. Your authentication values (key, name and password), recipient phone number “to”, your sender ID name or phone number “from” and text message “content”.

Mandatory parameters

ParameterDescriptionSample
from
One of the allowed sender settings (phone number or alphanumeric sender ID).447700809111 or YourBrand
to[]
Send messages to the mobile phone numbers in an international E.164 format. The use of a plus sign before dials is optional.447700809657 or +447700809657
content
The text of the message. Just like the others this content parameter should also be url-encoded. It may Sendberry test message contain any UTF-8 characters.Sendberry test message
key
Your API key.3398z931a9801de7c13e5a5dad00ee9
name
Your access name.Access name to be set in Sendberry Portal
password
Your access password.Access password to be set in Sendberry Portal

Limited or test mode

If you send messages while in limited or test mode, you must first verify your "from" Sender ID or use default one "Info SMS". Using free credits you can send messages "to[]" to your own phone number only, you may verify your number in Settings.
If you attempt to send an SMS using unverified Sender ID "from" or phone number "to[]", the API will return error.

Optional parameters

ParameterDescriptionSample
SMS_ID
Custom message ID. You can use your own IDs to identify the delivery reports more easily.00545454
date
Schedule a message in order to send it in concrete time in future. The date should be set in dd.mm.yyyy format. Default time is 09:00 if not set.12.05.2020
time
Schedule a message in order to send it in concrete time. The time format is HH:MM. If the date is not set messages will be sent in the same day.13:00
webhook
Your webhook URL will be triggered immediately after the sent message status is changed. API will send a POST request.https://yourdomain.com/webhook
inbox
In case the request is sent using your personal phone number the API will send all incoming SMS messages to defined webhook address.https://yourdomain.com/chat
response
The response format, GET or JSON.GET or JSON
If your request is unsuccessful you will receive an HTTP error code along with an error message.

Example request

You can also send a message to many recipients simultaneously, simply add additional phone number using “to[]” parameter
<?php
// PHP SOLUTION
$url = 'https://api.sendberry.com/SMS/SEND';
$recepients[] = "447700809111";
$recepients[] = "447700809112";
$recepients[] = "447700809113";
$data["key"] = "API KEY";
$data["name"] = "USERNAME";
$data["password"] = "PASSWORD#";
$data["content"] = "Welcome to Sendberry";
$data["from"] = "Info SMS";
$data["webhook"] = "WEBHOOK FOR QUERY RESULT";
$data["id"] = "YOUR OWN SMS ID TO LINK WITH";
$data["inbox"] = "WEBHOOK FOR RECIEVING SMS";
$data["response"] = "JSON"; // Optional. (JSON or GET)
$data_string = "";
foreach ($data AS $k=>$v) $data_string.=($data_string==""?"?":"&")."$k=".urlencode($v);
$to = implode("&to[]=",$recepients);
$data_string.= "&to[]=".$to;
$url.=$data_string;
$response = file_get_contents($url);
var_dump(json_decode($response,true)); //RESPONSE
var url = "https://api.sendberry.com/SMS/SEND";
var params = new Object;
params.key = 'API key';
params.name = "Username";
params.password = "Password";
params.content = "Welcome to Sendberry";
params.to[0] = "447700809111";
params.to[1] = "447700809112";
params.to[1] = "447700809113";
request.from = "Sendberry";
request.SMS_ID = "UNIQUE REFERENCE"; // Optional. SMS campaign reference.
request.callback = "CALLBACK URL FOR QUERY RESULT"; // Optional.
request.chatcallback = "SMS ANSWERS WEBHOOK";
request.responseformat = "JSON" // Optional. (JSON or GET)
var MyRequest = new XMLHttpRequest();
MyRequest.open('POST', url, true);
MyRequest.setRequestHeader('Content-type', 'application/x-www-form- urlencoded');
MyRequest.onreadystatechange = function() {//Call a function when the state changes.
  if(MyRequest.readyState == 4 && MyRequest.status == 200) {
    var response = this.responseText; // Handle the result
  }
} 
MyRequest.send(request);

Responses

As soon as you have sent a message, the Sendberry API will bring your campaign ID back and response status details. Also, you can track the delivery status changes using this ID.
ParameterDescriptionSample
status
Request confirmation.ok, error
ID
Sendberry campaign ID which can be used to check delivery status.AA000133
price
The cost of SMS message according to the rate and count of messages.0.025
count
The parts of SMS messages used to deliver your content.2
SMS_ID
Your own optional campaign ID if it’s set in API request.Your_ID_0001
Example JSON response
{
"status": "ok", // Status of the request
"cost": 0.074, // Price of message sent
"count": 2, // SMS parts
"ID": "AA000133", // SMS ID set by the platform
"SMS_ID": "" // SMS ID if set by you
}

Response sent in raw JSON by default. Use optional parameter “response” to change it

Delivery receipts

Immediately after the delivery confirmation is received from the carrier, Sendberry can inform you about the message delivery status. This status will indicate whether the carrier was successful in delivering the message to the handset or an error occurred.
Delivery notifications are provided using the following methods:
Sendberry portal — Each message status can be obtained by visiting your account at app.sendberry.com
Webhook — Sendberry is able to send to your web application an HTTP request when Delivery report status changed. See webhook documentation for more details.
HTTP API request — In order to track the delivery status send API request using SMS “ID” assigned by the system, or your personal ID “SMS_ID” (in case your have selected your personal ID in an API-request).
The request should be sent to following API address:
 https://api.sendberry.com/SMS/REPORT

Status codes
Description of the SMS message status codes.
ParameterDescription
sent
The message has been successfully sent.
delivered
The message has been delivered.
undelivered
The message is undeliverable. (Possibly because the device is unavailable for more than 48 hours or the mobile phone number is incorrect.
failed
The message delivery has been rejected by the carrier.
error
Your request has failed. This may happen due to various reasons including problems with number, account suspensions, missing values or even incorrect sender ID. Contact Sendberry support team for more information.

<?php
// PHP SOLUTION
$url = 'https://api.sendberry.com/SMS/STATUS';
$data["key"] = "API KEY";
$data["name"] = "USERNAME";
$data["password"] = "PASSWORD";
$data["id"] = "AA000133"; // Campaign ID received from Sendberry
$data["SMS_ID"] = "Your_ID_01212"; // Campaign ID set by you
$data_string = "";
foreach ($data AS $k=>$v)
$data_string.=($data_string==""?"?":"&")."$k=$v";
$url.=$data_string;
$response = file_get_contents($url);
var_dump(json_decode($response,true)); //RESPONSE
var url = "https://api.sendberry.com/SMS/STATUS";
var params = new Object;
params.key = 'API key';
params.name = "Username";
params.password = "Password";
params.id = "AA000133"; // Campaign ID received from Sendberry
params.SMS_ID = "Your_ID_01212"; // Campaign ID set by you
var MyRequest = new XMLHttpRequest();
MyRequest.open('POST', url, true);
MyRequest.setRequestHeader('Content-type', 'application/x-www-form- urlencoded');
MyRequest.onreadystatechange = function() {//Call a function when the state changes.
  if(MyRequest.readyState == 4 && MyRequest.status == 200) {
    var response = this.responseText; // Handle the response
  }
} 
MyRequest.send(request);

Example JSON response
Following details can be obtained by sending HTTP API request or sent to your webhook.
{
  "SMS_ID": "CAMPID00001",
  "ID": "AA00127",
  "content": "Hello world",
  "from": "Info SMS",
  "date_created": "01.01.2021",
  "recipients": [
    {
      "to": "447700809111",
      "sent_at": "2020-01-01 15:27:01",
      "last_update": "2020-01-01 15:27:11",
      "price": "0.022",
      "delivery_status": "Delivered",
      "delivery_message": "", // Additional delivery status details in case provided by Mobile Operator
      "delivery_code": "", // Additional delivery status details in case provided by Mobile Operator
      "delivery_time": "01.01.2020 15:27:06"
    }
  ]
}
Important parameters

ParameterDescription
SMS_ID
Your own SMS ID, if set in request.
id
Sendberry campaign ID.
sent_at
The time and date when message was sent.
delivery_time
Actual message delivery time.
delivery_status
The status of delivery, see status codes for more details.

Receiving SMS messages

If you want the notifications about the incoming messages to be sent to your server or those to be available in Sendberry portal, you need to order your own assigned phone number which will be used as your Sender ID in outgoing messages.
Message receiving procedure might be carried out by using webhook callback or Sendberry inbox portal. Your webhook address can be set for each API request using parameter “inbox” as well as you can set default webhook by logging into your account and setting default address in SMS webhook Two-Way section. Advanced API settings to be found here: https://app.sendberry.com/en/AdvancedApi.
Parameters
ParameterDescription
sms_date
Date and time of incoming SMS.
sms_from
Sender’s phone number.
sms_to
Your personal Sendberry phone number.
sms_text
Message content.

Example JSON response
{
"sms_date": "2019-01-01 00:55:00", 
"sms_from" "447700809663", 
"sms_to": "447700809654", 
"sms_text": "SMS message content" 
}

Reading SMS messages manually

You are able to read incoming SMS messages manually by sending API request with your authorisation details to the following address using your key, name and password.
 https://api.sendberry.com/SMS/INBOX

Example request
If the date_from or date_to not set the API will return all messages.
<?php
// PHP SOLUTION
$url = 'https://api.sendberry.com/SMS/INBOX';
$data["key"] = "API KEY";
$data["name"] = "USERNAME";
$data["password"] = "PASSWORD";
$data["number_from"] = "PHONE NUMBER"; // Sender's phone number or your subscriber
$data["number_to"] = "SENDBERRY NUMBER"; // Sender ID, your dedicated Sendberry number
$data["date_from"] = "11.01.2021"; 
$data["date_to"] = "11.02.2021"; 

$data_string = "";
foreach ($data AS $k=>$v)
$data_string.=($data_string==""?"?":"&")."$k=$v";
$url.=$data_string;
$response = file_get_contents($url);
var_dump(json_decode($response,true)); //RESPONSE
var url = "https://api.sendberry.com/SMS/INBOX";
var params = new Object;
params.key = 'API key';
params.name = "Username";
params.password = "Password";
params.number_from = "PHONE NUMBER"; // Sender's phone number or your subscriber
params.number_to = "SENDBERRY NUMBER"; // Sender ID, your dedicated Sendberry number
params.date_from = "11.01.2021";
params.date_to = "11.02.2021";
var MyRequest = new XMLHttpRequest();
MyRequest.open('POST', url, true);
MyRequest.setRequestHeader('Content-type', 'application/x-www-form- urlencoded');
MyRequest.onreadystatechange = function() {//Call a function when the state changes.
  if(MyRequest.readyState == 4 && MyRequest.status == 200) {
    var response = this.responseText; // Handle the response
  }
} 
MyRequest.send(request);

Webhook

Sendberry is able to send to your web application an HTTP request when certain events happen such as Delivery report or an income of SMS messages to one of your Sendberry phone numbers. These requests are called webhooks or status callbacks.
Sendberry can activate webhooks for new incoming message delivery reports and unsubscribes. You are now able to arrange your own scripts which will be interacting with all events on your platform.
Requests will be generated from following IP addresses:
 2.58.16.164
To set the default URLs for your webhooks visit the advanced API tab in the API section of settings.

Blacklist recipients

Exclude uninterested customers from your messaging campaigns by adding the phone number to the blacklist. The phone numbers in the blacklist will be automatically ignored.
Send your request using your authorisation details to the following address:
 https://api.sendberry.com/CONTACT/BLACKLIST

Parameters
ParameterDescription
add
The function allows you to add the number to blacklist.
remove
The function allows you to remove the number from the blacklist.
list
The function allows you to check if the number has already been included to blacklist.
Example request

<?php
// PHP SOLUTION
$url = 'https://api.sendberry.com/CONTACT/BLACKLIST';
$data["key"] = "API KEY";
$data["name"] = "USERNAME";
$data["password"] = "PASSWORD";
$data["number"] = "447700809111"; // Specify the phone number.
// Use only one action per request
$data["action"] = "add"; // Possible values: add, list or remove.
$data_string = "";
foreach ($data AS $k=>$v)
$data_string.=($data_string==""?"?":"&")."$k=$v";
$url.=$data_string;
$response = file_get_contents($url);
var_dump(json_decode($response,true)); //RESPONSE
var url = "https://api.sendberry.com/SMS/BLACKLIST";
var params = new Object;
params.key = 'API key';
params.name = "Username";
params.password = "Your Password";
$params.number = "447700809111";    // Specify the phone number.

// Use only one action per request
$params.action = "add";    // Possible values: add, list or remove.
var MyRequest = new XMLHttpRequest();
MyRequest.open('POST', url, true);
MyRequest.setRequestHeader('Content-type', 'application/x-www-form- urlencoded');
MyRequest.onreadystatechange = function() {//Call a function when the state changes.
  if(MyRequest.readyState == 4 && MyRequest.status == 200) {
    var response = this.responseText; // Handle the response
  }
} 
MyRequest.send(request);

Response example
{
"number": "447700809111", 
"action": "add",  // Request to add the phone number to blacklist
"result": "Success" // Request confirmation
}
{
"number": "447700809111", 
"name": "John",  // The name in case found in Contacts
"surname": "Doe" // The surname in case found in Contacts
}
{
"number": "447700809111", 
"action": "remove",  // Request to remove the phone number from blacklist
"result": "Success" // Request confirmation
}

Account balance

There is an additional function which allows you to check the current account balance. Send your authorisation details to address:
 https://api.sendberry.com/STATUS/BALANCE

<?php
// PHP SOLUTION
$url = 'https://api.sendberry.com/STATUS/BALANCE';
$data["key"] = "API KEY"; // Your API Key
$data["name"] = "USERNAME"; // Your username
$data["password"] = "PASSWORD"; // Your password
$data_string = "";
foreach ($data AS $k=>$v)
$data_string.=($data_string==""?"?":"&")."$k=$v";
$url.=$data_string;
$response = file_get_contents($url);
var_dump(json_decode($response,true)); //RESPONSE
var url = "https://api.sendberry.com/SMS/BALANCE";
var params = new Object;
params.key = 'API key';
params.name = "Username";
params.password = "Your Password";
var MyRequest = new XMLHttpRequest();
MyRequest.open('POST', url, true);
MyRequest.setRequestHeader('Content-type', 'application/x-www-form- urlencoded');
MyRequest.onreadystatechange = function() {//Call a function when the state changes.
  if(MyRequest.readyState == 4 && MyRequest.status == 200) {
    var response = this.responseText; // Handle the response
  }
} 
MyRequest.send(request);

Response example
 {
"balance": 170.425,  // Your available balance
"credit_limit": 200 // Your available credit limit
}
Get in touch or create free account

Ready to get started?


Our bulk SMS service comes with cutting-edge tools which help to make your text messages go even farther and achieve better results.


Sign up for free
Still inquiring? Contact sales
English