API for sending SMS http/POST
The API SMS http/POST is designed for technicians and customers who want to connect their applications to LabsMobile's SMS messaging platform.
The functionalities of the SMS http/POST API are:
- The sending of SMS messages individually or massively in real time.
- Scheduled sending of SMS messages.
- Sending SMS Unicode, SMS Concatenated messages and SMS Certified messages.
- Consulting the balance of credits in an account
This documentation explains in detail the process of integration and automation of these functionalities.
To start an integration with the http/POST API the following requirements are essential:
- A LabsMobile account associated with a username (registration email). Create an account here.
- API token used as password and generated from the API Settings section of your account.
- URL of the http/POST API endpoint and the parameter values to make the request.
To be taken into account
The LabsMobile http/POST API is a REST API that uses the HTTP POST protocol, the JSON format for information exchange and a common base URL for all requests: https://api.labsmobile.com/json/
.
It is recommended to use a URL that includes the HTTPS
protocol in any version of our API.
Authentication
The authentication method used is Auth Basic HTTP.
This type of authentication consists of username:tokenapi
credentials that are included in the HTTP request header encoded in base64()
.
Authorization: Basic 9yewaXic21vYmlsZqS5jmSk04enFTbUU=
Recommendation You can generate API tokens from the API Settings of the account. We recommend changing the token frequently and using different tokens for each use, connection or integration.
Configuration and filters
The following are important configuration variables and security aspects in an integration with the SMS http/GET API:
- IP address from which messages will be sent. If this option is enabled, only requests from the list of IP addresses entered will be accepted. This functionality is optional, by default messages will be accepted from any IP.
- Default sender (default
LABSMOBILE
). Only some operators allow dynamic, alphanumeric-valued mapping of the sender field. - Daily message limit, by default 100,000 sms/day.
- Message limit per batch, default 10,000 sms/request.
- Country filter, so that only messages from a list of countries are processed.
- Anti-duplication filter, to avoid sending identical messages to the same recipient.
All these parameters can be activated and modified in the API Settings and Account Preferences.
Important A maximum of 10 requests per second is established. Misuse, abuse or a higher volume of requests will result in a temporary or permanent blocking of the account and/or IP address.
Recommendation We recommend activating the Automatic Top-Ups so that there are always credits available in the account and the SMS sending service is not interrupted.
Sending SMS messages
Petition for sending SMS messages individually or in bulk.
With this functionality, messages can be sent in real time or scheduled for a specific day and time. In addition, other parameters such as sender, label, identifier, simulated mode, etc. can be added.
ENDPOINT
POST https://api.labsmobile.com/json/send
- Expand all
PARAMETERS
The parameters or data are sent in the body of an http/POST call in
JSON
format. The values and functionality of all parameters are described below.Example JSON format{ "message":"Message text", "tpoa":"Sender", "recipient": [ {"msisdn":"12015550123"}, {"msisdn":"12015550124"}, {"msisdn":"12015550125"}, ], "test":"1", "subid":"L-203", "label":"from]=websms;[user]=admin[campaign]=salesJanuary" }
recipient array mandatory
List of recipient numbers. Array of parameters
msisdn
.msisdn string mandatory
Telephone numbers of the recipients to whom the message is sent. The numbers must comply with the international format E.164 and separated by commas (",") if more than one destination number is included.
Example:
"msisdn":"34609033162"
message string mandatory
Text of the message to be sent. When sending standard SMS only GSM 3.38 7bit alphabet characters are valid. You can also send Concatenated SMS, Unicode SMS and Certified SMS with the corresponding parameters.
Example:
"message": "Hello world!"
.scheduled YYYY-MM-DD HH:MM:SS
Scheduling of sending for the day and time indicated. If this field is not specified, the message will be sent immediately. Format:
YYYYYY-MM-DD HH:MM:SS
.Important: The value of this field must be expressed in GMT time zone.
Example:
"scheduled": "2024-04-12 10:00:00"
.tpoa string
SMS message sender field. It can have a numeric value (maximum length 16 digits) or an alphanumeric value (maximum length 11 characters).
Sender assignment and customization is only available in some countries and operators. Otherwise, the sender will be a static numeric value (shortcode or longcode).
Example:
"tpoa": "MyBrand"
.subid string
Request identifier. Maximum length of 20 characters.
If no value is included in the
subid
parameter, the platform will assign a unique 13-character identifier that will be displayed in the request result.Example:
"subid": "5aa3ea802828ce5"
.label string
Free information field to identify and assign attributes. Maximum length of 255 characters.
Possible uses: user, application, grouping or campaign, etc.
Example:
"label": "A05-Jan-2024"
.test 0 | 1
Activation of simulated send mode for testing and monitoring.
If a value
1
is assigned to this parameter, the messages will not be sent to the recipients and no credit will be deducted. Messages sent in simulated mode will be available in the History and other tools.Example:
"test": 1
.ackurl url
Url to which delivery confirmation and error notifications of sent messages will be sent.
A default URL can be set in the Account API Settings and in that case it is not necessary to include this parameter.
Example:
"ackurl": "https://clientserver.com/receive_ack"
.clickurl url
Url to which the event notifications will be sent when clicking on the links in the sent messages.
A default URL can be set in the Account API Settings and in that case it is not necessary to include this parameter.
Example:
"clickurl": "https://clientserver.com/receive_click"
.shortlink 0 | 1
Activation of automatic link replacement.
If its value is
1
all Urls in the message will be replaced with a short link (format:labsmo.bi/XXXXXXXXX
or custom domain).You can enable this feature permanently for all messages in the Account Preferences and in that case you do not need to include this parameter.
Example:
"shortlink": 1
.long 0 | 1
Activation of the SMS Concatenated in this request.
If this field has value
1
the message can contain more than 160 characters. Learn more about How to calculate the price of an SMS.Example:
"long": 1
.ucs2 0 | 1
Activation of the SMS Unicode in this request.
If this field has value
1
the message can contain any character, symbol or emoji. The capacity is reduced to 70 characters and concatenated and unicode SMS can be sent. Learn more about How to calculate the price of an SMS.Example:
"ucs2": 1
.crt email
Sending a SMS Certificate in this request.
An e-mail with the certification PDF document will be sent to the address containing this parameter.
Example:
"crt": "info@client.es"
.crt_name string
Name of the entity or company sending the certified SMS. Only effective if sent together with the
crt
parameter.Example:
"crt_name": "My Company SL"
.crt_id string
Fiscal identifier of the entity or company sending the certified SMS. Only effective if sent together with the
crt
parameter.Example:
"crt_id":"ESB65213332"
crt_lang string
Certificate language. Only effective if sent together with the
crt
parameter.Values:
ES
EN
CA
FR
DE
IT
IT
NL
PT
NL
DA
SV
PL
RO
RO
EL
EL
.Ejemplo:
"crt_lang": "EN"
.nofilter 0 | 1
If this field has value
1
the duplicate message filter will not be applied.You can permanently enable or disable this feature for all messages in the Account Preferences and in that case you do not need to include this parameter.
Example:
"nofilter": 1
.parameters json
This field contains values for replacing parameters in the message text. The message can contain one or more parameters (with the following format: %name%, %fieldn%, etc.). It is necessary to specify the value of each parameter for each recipient or set a default value.
Example:
"parameters": [
.{"name": {"msisdn": "12015550123", "value": "John"}}, {"name": {"msisdn": "default", "value": "Client"}}}] RESULT
The result is obtained in
JSON
format with the following elements:code integer
Identifier code indicating whether the request could be processed successfully or if an error occurred. Possible values in the Errors section.
Example:
"code": "0"
.message string
Description indicating whether the request could be processed successfully or if an error occurred. Possible values in the Errors section.
Example:
"message": "Message has been success
.fully sent." subid string
API request identifier.
Example:
"subid": "661568648080e47"
.Example code
Sending a standard message to a single recipient:
Individual sendingcurl --user myUsername:myToken -X POST \ https://api.labsmobile.com/json/send \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d '{"message":"Your verification code is 123", "tpoa":"Sender","recipient":[{"msisdn":"12015550123"}]}'
#include <stdio.h> #include <curl/curl.h> int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_easy_setopt(curl, CURLOPT_URL, "https://api.labsmobile.com/json/send"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC); curl_easy_setopt(curl, CURLOPT_USERNAME, "myUsername"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "myToken"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Cache-Control: no-cache"); headers = curl_slist_append(headers, "Content-Type: application/json"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = "{\r\n \"message\":\"Your verification code is 123\",\r\n \"tpoa\":\"Sender\",\r\n \"recipient\":\r\n [\r\n {\r\n \"msisdn\":\"12015550123\"\r\n }\r\n ]\r\n}\r\n\r\n"; curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); res = curl_easy_perform(curl); if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } return 0; }
using System; using RestSharp; namespace SendPostUni { class Program { static void MainSend(string[] args) { var client = new RestClient("https://api.labsmobile.com"); var request = new RestRequest("/json/send", Method.Post); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("myUsername" + ":" + "myToken"))); request.AddParameter("application/json", "{\r\n \"message\":\"Your verification code is 123\",\r\n \"tpoa\":\"Sender\",\r\n \"recipient\":\r\n [\r\n {\r\n \"msisdn\":\"12015550123\"\r\n }\r\n ]\r\n}\r\n\r\n", ParameterType.RequestBody); RestResponse response = client.Execute(request); if (response.ErrorException != null) { Console.WriteLine("Error: " + response.ErrorException.Message); } else { Console.WriteLine("Response content: " + response.Content); } } } }
import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; public class App { public static void main(String[] args) throws UnirestException { Unirest.setTimeouts(0, 0); HttpResponse<String> response = Unirest.post("https://api.labsmobile.com/json/send") .header("Content-Type", "application/json") .basicAuth("myUsername", "myToken") .header("Cache-Control", "no-cache") .body( "{\"message\":\"Your verification code is 123\", \"tpoa\":\"Sender\",\"recipient\":[{\"msisdn\":\"12015550123\"}]}") .asString(); System.out.println("Status code: " + response.getBody()); } }
<?php $auth_basic = base64_encode("myUsername:myToken"); $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.labsmobile.com/json/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 => '{ "message":"Your verification code is 123", "tpoa":"Sender", "recipient": [ { "msisdn":"12015550123" } ] }', CURLOPT_HTTPHEADER => array( "Authorization: Basic ".$auth_basic, "Cache-Control: no-cache", "Content-Type: application/json" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
import requests, base64, json userToken = "myUsername:myToken" credentials = (base64.b64encode(userToken.encode()).decode()) url = "https://api.labsmobile.com/json/send" payload = json.dumps({ "message": "Your verification code is 123", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" } ] }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % credentials, 'Cache-Control': "no-cache" } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)
const axios = require('axios'); const data = JSON.stringify({ "message": "Your verification code is 123", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" } ] }); let config = { method: 'post', maxBodyLength: Infinity, url: 'https://api.labsmobile.com/json/send', headers: { 'Content-Type': 'application/json', 'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64') }, data : data }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); });
require "uri" require "json" require 'base64' require "net/http" url = URI("https://api.labsmobile.com/json/send") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Basic " + Base64.strict_encode64("myUsername:myToken") request.body = JSON.dump({ "message": "Your verification code is 123", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" } ] }) response = https.request(request) puts response.read_body
Multiple sendingcurl --user myUsername:myToken -X POST \ https://api.labsmobile.com/json/send \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d '{"message":"Do not miss our Sale! Use code XXXX123 for 20% off.", "tpoa":"Sender","recipient":[{"msisdn":"12015550123"},{"msisdn":"12015550124"},{"msisdn":"12015550125"}]}'
#include <stdio.h> #include <curl/curl.h> int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_easy_setopt(curl, CURLOPT_URL, "https://api.labsmobile.com/json/send"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC); curl_easy_setopt(curl, CURLOPT_USERNAME, "myUsername"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "myToken"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Cache-Control: no-cache"); headers = curl_slist_append(headers, "Content-Type: application/json"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = "{\r\n \"message\":\"Do not miss our Sale! Use code XXXX123 for 20% off.\",\r\n \"tpoa\":\"Sender\",\r\n \"recipient\":\r\n [\r\n {\r\n \"msisdn\":\"12015550123\"\r\n },\r\n {\r\n \"msisdn\":\"12015550124\"\r\n },\r\n {\r\n \"msisdn\":\"12015550125\"\r\n }\r\n ]\r\n}\r\n\r\n"; curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); res = curl_easy_perform(curl); if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } return 0; }
using System; using RestSharp; namespace SendPostMul { class Program { static void MainSend(string[] args) { var client = new RestClient("https://api.labsmobile.com"); var request = new RestRequest("/json/send", Method.Post); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("myUsername" + ":" + "myToken"))); request.AddParameter("application/json", "{\r\n \"message\":\"Don't miss our Sale! Use code XXXX123 for 20% off.\",\r\n \"tpoa\":\"Sender\",\r\n \"recipient\":\r\n [\r\n {\r\n \"msisdn\":\"12015550123\"\r\n },\r\n {\r\n \"msisdn\":\"12015550124\"\r\n },\r\n {\r\n \"msisdn\":\"12015550125\"\r\n }\r\n ]\r\n}\r\n\r\n", ParameterType.RequestBody); RestResponse response = client.Execute(request); if (response.ErrorException != null) { Console.WriteLine("Error: " + response.ErrorException.Message); } else { Console.WriteLine("Response content: " + response.Content); } } } }
import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; public class App { public static void main(String[] args) throws UnirestException { Unirest.setTimeouts(0, 0); HttpResponse<String> response = Unirest.post("https://api.labsmobile.com/json/send") .header("Content-Type", "application/json") .basicAuth("myUsername", "myToken") .header("Cache-Control", "no-cache") .body( "{\"message\":\"Don't miss our Sale! Use code XXXX123 for 20% off.\", \"tpoa\":\"Sender\",\"recipient\":[{\"msisdn\":\"12015550123\"},{\"msisdn\":\"12015550124\"},{\"msisdn\":\"12015550125\"}]}") .asString(); System.out.println("Status code: " + response.getBody()); } }
<?php $auth_basic = base64_encode("myUsername:myToken"); $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.labsmobile.com/json/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 => '{ "message":"Do not miss our Sale! Use code XXXX123 for 20% off.", "tpoa":"Sender", "recipient": [ { "msisdn":"12015550123" }, { "msisdn":"12015550124" }, { "msisdn":"12015550125" } ] }', CURLOPT_HTTPHEADER => array( "Authorization: Basic ".$auth_basic, "Cache-Control: no-cache", "Content-Type: application/json" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
import requests, base64, json userToken = "myUsername:myToken" credentials = (base64.b64encode(userToken.encode()).decode()) url = "https://api.labsmobile.com/json/send" payload = json.dumps({ "message": "Don't miss our Sale! Use code XXXX123 for 20% off.", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" }, { "msisdn": "12015550124" }, { "msisdn": "12015550125" } ] }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % credentials, 'Cache-Control': "no-cache" } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)
const axios = require('axios'); const data = JSON.stringify({ "message": "Don't miss our Sale! Use code XXXX123 for 20% off.", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" }, { "msisdn": "12015550124" }, { "msisdn": "12015550125" } ] }) let config = { method: 'post', maxBodyLength: Infinity, url: 'https://api.labsmobile.com/json/send', headers: { 'Content-Type': 'application/json', 'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64') }, data : data }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); });
require "uri" require "json" require 'base64' require "net/http" url = URI("https://api.labsmobile.com/json/send") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Basic " + Base64.strict_encode64("myUsername:myToken") request.body = JSON.dump({ "message": "Don't miss our Sale! Use code XXXX123 for 20% off.", "tpoa": "Sender", "recipient": [ { "msisdn": "12015550123" }, { "msisdn": "12015550124" }, { "msisdn": "12015550125" } ] }) response = https.request(request) puts response.read_body
Positive result{ "subid": "65f33a88ceb3d", "code": "0", "message": "Message has been successfully sent." }
Wrong result{ "subid": "65f7f7041385d", "code": "35", "message": "The account has no enough credit for this sending" }
Balance inquiry
Consult on the number of available credits of an account.
ENDPOINT
GET https://api.labsmobile.com/json/balance
This functionality has no parameters, just send the correct credentials to identify the account to the balance inquiry endpoint.
RESULT
The result of any SMS http/POST API request is obtained in
JSON
format with the following elements:code integer
Identifier code indicating whether the request could be processed successfully or if an error occurred. Possible values in the Errors section.
Example:
"code": "0"
.message string
Description of the error in the request. If the request has been processed correctly this field does not appear.
Example:
"message": "Unauthorized"
.credits float
Number of credits available in the account balance.
Example:
"credits": "1023.10"
.
curl --user myUsername:myToken -X GET \ https://api.labsmobile.com/json/balance \ -H 'Cache-Control: no-cache' \
#include <stdio.h> #include <curl/curl.h> int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "GET"); curl_easy_setopt(curl, CURLOPT_URL, "https://api.labsmobile.com/json/balance"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC); curl_easy_setopt(curl, CURLOPT_USERNAME, "myUsername"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "myToken"); struct curl_slist *headers = NULL; curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = ""; curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); res = curl_easy_perform(curl); if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } return 0; }
using System; using RestSharp; namespace BalancePost { class Program { static void MainBalance(string[] args) { var client = new RestClient("https://api.labsmobile.com"); var request = new RestRequest("/json/balance", Method.Get); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("myUsername" + ":" + "myToken"))); RestResponse response = client.Execute(request); if (response.ErrorException != null) { Console.WriteLine("Error: " + response.ErrorException.Message); } else { Console.WriteLine("Response content: " + response.Content); } } } }
import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; public class App { public static void main(String[] args) throws UnirestException { Unirest.setTimeouts(0, 0); HttpResponse<String> response = Unirest.get("https://api.labsmobile.com/json/balance") .header("Content-Type", "application/json") .basicAuth("myUsername", "myToken") .header("Cache-Control", "no-cache") .body("") .asString(); System.out.println("Status code: " + response.getBody()); } }
<?php $auth_basic = base64_encode("myUsername:myToken"); $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.labsmobile.com/json/balance", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => array( "Authorization: Basic ".$auth_basic, "Cache-Control: no-cache", ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
import requests, base64, json userToken = "myUsername:myToken" credentials = (base64.b64encode(userToken.encode()).decode()) url = "https://api.labsmobile.com/json/balance" payload = "" headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % credentials, 'Cache-Control': "no-cache" } response = requests.request("GET", url, headers=headers, data=payload) print(response.text)
const axios = require('axios'); let data = ''; let config = { method: 'get', maxBodyLength: Infinity, url: 'https://api.labsmobile.com/json/balance', headers: { 'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64') }, data : data }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); });
require "uri" require "json" require 'base64' require "net/http" url = URI("https://api.labsmobile.com/json/balance") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Basic " + Base64.strict_encode64("myUsername:myToken") request.body = "" response = https.request(request) puts response.read_body
{ "code":0, "credits":"10" }
{ "code":"403", "message":"Forbidden" }
Price inquiry
Consult on the tariff (in credits) for one or more destination countries.
ENDPOINT
GET https://api.labsmobile.com/json/prices
PARAMETERS
The parameters or data are sent in the body of an http/POST call in
JSON
format. The values and functionality of all parameters are described below.countries array
List of countries for which you want to obtain the updated rate in credits and other details. Format: ISO codes of the countries. If this field is not sent or is null, information for all countries is returned.
Example:
"countries":["ES", "FR",
."US", "MX"] format string
Desired format in the result of the request. Values:
JSON
(default)XML
CSV
.Example:
"format": "CSV"
.
- Expand all
RESULT
The result is obtained in
JSON
,XML
orCSV
format with the following elements: isocode float
ISO code that identifies the country.
Example:
"isocode": "FR"
.prefix float
Telephone prefix of the country.
Example:
"prefix": "33"
.name float
Descriptive name of the country in English.
Example:
"name": "France"
.credits float
Number of credits available in the account balance.
Example:
"credits": 0.89
.code integer
Identifier code indicating the error occurred. Possible values in the Errors section. If the request has been processed correctly this field does not appear.
Example:
"code": "401"
.message string
Description of the error in the request. If the request has been processed correctly this field does not appear.
Example:
"message": "Unauthorized"
.
curl --user myusername:mypassword -X POST \ https://api.labsmobile.com/json/prices \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d '{"format":"JSON","countries":["ES","FR","US","MX"]}'
#include <stdio.h> #include <curl/curl.h> int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_easy_setopt(curl, CURLOPT_URL, "https://api.labsmobile.com/json/prices"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC); curl_easy_setopt(curl, CURLOPT_USERNAME, "myUsername"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "myToken"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Cache-Control: no-cache"); headers = curl_slist_append(headers, "Content-Type: application/json"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = "{\"format\":\"JSON\",\"countries\":[\"ES\",\"FR\",\"US\",\"MX\"]}"; curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); res = curl_easy_perform(curl); if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } return 0; }
using System; using RestSharp; namespace Prices { class Program { static void MainPrices(string[] args) { var client = new RestClient("https://api.labsmobile.com"); var request = new RestRequest("/json/prices", Method.Post); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("myUsername" + ":" + "myToken"))); request.AddParameter("application/json", "{\"format\":\"JSON\",\"countries\":[\"ES\",\"FR\",\"US\",\"MX\"]}", ParameterType.RequestBody); RestResponse response = client.Execute(request); if (response.ErrorException != null) { Console.WriteLine("Error: " + response.ErrorException.Message); } else { Console.WriteLine("Response content: " + response.Content); } } } }
import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; public class App { public static void main(String[] args) throws UnirestException { Unirest.setTimeouts(0, 0); HttpResponse<String> response = Unirest.post("https://api.labsmobile.com/json/prices") .header("Content-Type", "application/json") .basicAuth("myUsername", "myToken") .header("Cache-Control", "no-cache") .body( "{\"format\":\"JSON\",\"countries\":[\"ES\",\"FR\",\"US\",\"MX\"]}") .asString(); System.out.println("Status code: " + response.getBody()); } }
<?php $auth_basic = base64_encode("myUsername:myToken"); $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.labsmobile.com/json/prices", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => '{ "format":"JSON", "countries":["ES","FR","US","MX"] }', CURLOPT_HTTPHEADER => array( "Authorization: Basic ".$auth_basic, "Cache-Control: no-cache", "Content-Type: application/json" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
import requests, base64, json userToken = "myUsername:myToken" credentials = (base64.b64encode(userToken.encode()).decode()) url = "https://api.labsmobile.com/json/prices" payload = json.dumps({ "format":"JSON", "countries":["ES","FR","US","MX"] }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % credentials, 'Cache-Control': "no-cache" } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)
const axios = require('axios'); const data = JSON.stringify({ "format":"JSON", "countries":["ES","FR","US","MX"] }); let config = { method: 'post', maxBodyLength: Infinity, url: 'https://api.labsmobile.com/json/prices', headers: { 'Content-Type': 'application/json', 'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64') }, data : data }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); });
require "uri" require "json" require 'base64' require "net/http" url = URI("https://api.labsmobile.com/json/prices") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Basic " + Base64.strict_encode64("myUsername:myToken") request.body = JSON.dump({ "format":"JSON", "countries":["ES","FR","US","MX"] }) response = https.request(request) puts response.read_body
{ "FR": { "isocode":"FR", "prefix":"33", "name":"France", "credits":1.114 }, "DE": { "isocode":"DE", "prefix":"49", "name":"Germany", "credits":1.8 } }
{ "code": "401", "message": "Unauthorized" }
Managing scheduled sendings
Cancellation or execution of pending scheduled sengings.
ENDPOINT
POST https://api.labsmobile.com/json/
.
PARAMETERS
The parameters or data are sent in the body of an http/POST call in
JSON
format. The values and functionality of all parameters are described below.subid string mandatory
Identifier of the scheduled sending request. If this parameter has
*
as value it will affect all pending scheduled sendings on the account.Example:
"subid": "5aa3ea8e5cdb6"
.cmd string mandatory
Command to execute. Possible values:
cancel
send
, to delete or execute at that moment the selected programmed sendings.Example:
"cmd": "send"
.RESULT
The result is obtained in
JSON
format with the following elements:code integer
Identifier code indicating whether the request could be processed successfully or if an error occurred. Possible values in the Errors section.
Example:
"code": "0"
.message string
Description indicating whether the request could be processed successfully or if an error occurred. Possible values in the Errors section.
Example:
"message": "Scheduled messages success
.fully cancelled."
curl --user myusername:mypassword -X POST \ https://api.labsmobile.com/json/scheduled \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -d '{"cmd":"cancel","subid":"5a9fe45c7adc3"}'
#include <stdio.h> #include <curl/curl.h> int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_easy_setopt(curl, CURLOPT_URL, "https://api.labsmobile.com/json/scheduled"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC); curl_easy_setopt(curl, CURLOPT_USERNAME, "myUsername"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "myToken"); struct curl_slist *headers = NULL; headers = curl_slist_append(headers, "Cache-Control: no-cache"); headers = curl_slist_append(headers, "Content-Type: application/json"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); const char *data = "{\"cmd\":\"cancel\",\"subid\":\"5a9fe45c7adc3\"}"; curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); res = curl_easy_perform(curl); if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } return 0; }
using System; using RestSharp; namespace Prices { class Program { static void MainPrices(string[] args) { var client = new RestClient("https://api.labsmobile.com"); var request = new RestRequest("/json/scheduled", Method.Post); request.AddHeader("Cache-Control", "no-cache"); request.AddHeader("Content-Type", "application/json"); request.AddHeader("Authorization", "Basic " + Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("myUsername" + ":" + "myToken"))); request.AddParameter("application/json", "{\"cmd\":\"cancel\",\"subid\":\"5a9fe45c7adc3\"}", ParameterType.RequestBody); RestResponse response = client.Execute(request); if (response.ErrorException != null) { Console.WriteLine("Error: " + response.ErrorException.Message); } else { Console.WriteLine("Response content: " + response.Content); } } } }
import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; import com.mashape.unirest.http.exceptions.UnirestException; public class App { public static void main(String[] args) throws UnirestException { Unirest.setTimeouts(0, 0); HttpResponse<String> response = Unirest.post("https://api.labsmobile.com/json/scheduled") .header("Content-Type", "application/json") .basicAuth("myUsername", "myToken") .header("Cache-Control", "no-cache") .body( "{\"cmd\":\"cancel\",\"subid\":\"5a9fe45c7adc3\"}") .asString(); System.out.println("Status code: " + response.getBody()); } }
<?php $auth_basic = base64_encode("myUsername:myToken"); $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => "https://api.labsmobile.com/json/scheduled", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => '{ "cmd":"cancel", "subid":"5a9fe45c7adc3" }', CURLOPT_HTTPHEADER => array( "Authorization: Basic ".$auth_basic, "Cache-Control: no-cache", "Content-Type: application/json" ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; }
import requests, base64, json userToken = "myUsername:myToken" credentials = (base64.b64encode(userToken.encode()).decode()) url = "https://api.labsmobile.com/json/scheduled" payload = json.dumps({ "cmd":"cancel", "subid":"5a9fe45c7adc3" }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic %s' % credentials, 'Cache-Control': "no-cache" } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)
const axios = require('axios'); const data = JSON.stringify({ "cmd":"cancel", "subid":"5a9fe45c7adc3" }); let config = { method: 'post', maxBodyLength: Infinity, url: 'https://api.labsmobile.com/json/scheduled', headers: { 'Content-Type': 'application/json', 'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64') }, data : data }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); });
require "uri" require "json" require 'base64' require "net/http" url = URI("https://api.labsmobile.com/json/scheduled") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/json" request["Authorization"] = "Basic " + Base64.strict_encode64("myUsername:myToken") request.body = JSON.dump({ "cmd":"cancel", "subid":"5a9fe45c7adc3" }) response = https.request(request) puts response.read_body
{ "code":"0", "message":"Scheduled messages successfully cancelled." }
{ "code":"52", "message":"Scheduled messages not found." }
Receipt of statuses
Obtaining the status (delivered or error) of sent messages.
With this functionality, the client receives in a URL the delivery confirmation or error events of each message sent.
There are two methods to enable receiving statuses in a URL:
- Adding a URL in the
ackurl
parameter of the sending API request. - By entering a URL in the Account API Settings, in the URL for receiving confirmations or delivery errors field.
In both cases when a message delivered or error status occurs, an http/GET call will be made to the URL provided with the parameters detailed below.
- Expand all
PARAMETERS
subid string
Message identifier. This identifier is the one obtained as a result of an SMS sending API request.
Example:
&subid=5aa3ea8e5cdb6
.acklevel string
Message status.
Example:
&acklevel=handset
.Check type valuesoperator
Confirmation that the telephone operator has received the message, has validated it and is responsible for its delivery. handset
Message confirmed as delivered. error
Error in the delivery or communication of the SMS message. desc string
Description of the error in message delivery and communication.
Example:
&desc=REJECTD
.Check type valuesREJECTD
Message rejected due to operator or mobile device policy. EXPIRED
It was not possible to deliver the message because the recipient was not active during the delivery period (usually 72 hours). BLOCKED
Message blocked by a security or SPAM filter. UNDELIV
It has not been possible to deliver the message, usually because the number is incorrect. UNKNOWN
Unknown error or no description. status string
The value of this field indicates whether the message follows the normal delivery process or if an error has occurred. Values:
ok
ko
Example:
&status=ok
.timestamp YYYY-MM-DD HH:MM:SS
Day and time in GMT time use when the event occurred and the message reached the communicated state.
Example:
×tamp=2024-05-12%2012%3A23%3A00
msisdn string
Number of the message recipient.
Example:
&msisdn=5212221234567
URL format: ?acklevel=[gateway|operator|handset|error]
.
RetriesIf the http/GET call generates an error when calling the URL (HTTP 4xx or 5xx states) the delivery will be reattempted up to 5 times at the following intervals: 30s, 5m, 30m, 6h, 1d.
Receiving clicks
Getting the clicks on the URLs of sent messages.
With this functionality, click events that occur in sent messages are received in a URL of the client.
There are two methods to enable receiving clicks on a URL:
- Adding a URL in the
clickurl
parameter of the submit API request. - By entering a URL in the Configuration API of the account, in the URL for receiving visits or clicks field.
In both cases when a click on a URL occurs an http/POST JSON call will be made to the URL provided with the parameters detailed below.
- Expand all
PARAMETERS
subid string
Message identifier. This identifier is the one obtained as a result of an SMS sending API request.
Example:
"subid": "5aa3ea8e5cdb6"
.msisdn string
Number of the recipient of the message clicked.
Example:
"msisdn": "5212221234567"
.ip string
IP address of the user who visited the URL.
Example:
"ip": "98.139.180.149"
.useragent string
User agent with information about the browser and device that visited the URL.
Example:
"ip": "Mozilla/5.0
.(Windows NT 6.1; Win64; x64; rv: 47.0) Gecko/2010 010101 Firefox/47.0" timestamp YYYY-MM-DD HH:MM:SS
Day and time in GMT time zone when the click occurred.
Example:
"timestamp": "2024-05-12 12:23:00"
.
{ ip : "98.139.180.149", useragent : "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0", subid : "5aa3ea8e5cdb6", msisdn : "5212221234567", timestamp : "2018-03-18 15:23:10" }
RetriesIf the http/GET call generates an error when calling the URL (HTTP 4xx or 5xx states) the delivery will be reattempted up to 5 times at the following intervals: 30s, 5m, 30m, 6h, 1d.
Important In order to receive clicks, SMS messages must be delivered with a domain associated with the LabsMobile platform (labsmo.bi
or custom domain configured).
Message reception
Reception of SMS messages in the contracted virtual numbers.
With this functionality the received SMS messages are received in a URL of the client.
To enable receiving SMS messages on a URL you need to enter a URL in the Account API Settings, in the URL for receiving messages field.
When an SMS is received it will make an http/POST JSON call to the URL provided with the parameters listed below.
- Expand all
PARAMETERS
inbound_number string
Virtual number on which the message was received.
Example:
"inbound_number": "13098212823"
.msisdn string
Number that sent the message.
Example:
"msisdn": "447400826129"
.message string
Text of the message received.
Example:
Hello,
.I am sending a message to this service. service_number string
Virtual number where the SMS message was received.
Values:
13098212823
timestamp YYYY-MM-DD HH:MM:SS
Day and time in GMT time zone when the SMS message was received.
Example:
"timestamp": "2024-05-12 12:23:00"
.
{ "inbound_number":"12015576234", "service_number":"12015576234", "msisdn":"12015550123", "message":"Test message", "timestamp":"2014-06-07 19:21:43" }
RetriesIf the http/GET call generates an error when calling the URL (HTTP 4xx or 5xx states) the delivery will be reattempted up to 5 times at the following intervals: 30s, 5m, 30m, 6h, 1d.
Important To receive SMS messages it is necessary to contract virtual numbers for sending and receiving SMS.
Errors
The HTTP error codes that may be returned by a request to the SMS http/POST API are described below.
HTTP Code | Description |
---|---|
200 OK | Request processed correctly. |
400 Bad Request | Error in the request parameters. The error is detailed and specified in the code returned in JSON format. |
401 Unauthorized | Error in credentials or authentication method. |
402 Payment Required | Error due to lack of credits in the account. |
403 Forbidden | Request blocked by the IP filter or for violating any platform usage policy. |
500 Internal Server Error | Temporary error or incidence in the service |
This is the complete list of response codes in JSON format:
JSON Code | Description |
---|---|
0 | Message has been successfully sent |
10 | Missing XML data in request |
11 | Badly formed XML in request |
20 | The message element must be present in the request |
21 | The message element cannot be empty |
23 | There are no recipients |
24 | Too many recipients |
27 | This message contained one or more invalid character(s) |
28 | Subid is exceeding maximum length |
30 | There was an error while sending the message |
35 | The account has no enough credit for this sending |
39 | The value of the scheduled field is not a valid datetime format |
41 | Scheduled messages cannot be send in test mode |
51 | Compulsary fields not defined. |
52 | Scheduled messages not found. |
Support resources
We recommend that you consult and take into account the following support resources in your integration: