MENU' Navbar
smSend
SHELL JAVA PHP PYTHON NODEJS RUBY C# PERL

Introduction

Welcome to the smSend API documentation!

The API is divided into subsections, which are briefly described below. For details about each section, please refer to the respective section.

Quick start: full examples

Send an SMS message: Full example

echo 'Full example not available for shell'
import java.io.BufferedReader;
        import java.io.IOException;
        import java.io.InputStreamReader;
        import java.io.OutputStream;
        import java.net.HttpURLConnection;
        import java.net.URL;
        import java.util.ArrayList;
        import java.util.Date;
        import java.util.List;
        // This example requires Gson configured in the build path (for JSON support):
        // https://github.com/google/gson
        import com.google.gson.Gson;
        import com.google.gson.GsonBuilder;
        public class Main {
        public static final String BASEURL = "http://app.gateway.smsend.it/API/v1.0/REST/";
        public static final String MESSAGE_HIGH_QUALITY = "N";
        public static final String MESSAGE_MEDIUM_QUALITY = "L";
        public static final String MESSAGE_LOW_QUALITY = "LL";
        public static void main(String[] args) {
        try {
        String[] authKeys = login("username", "password");
        SendSMSRequest sendSMS = new SendSMSRequest();
        sendSMS.setMessage("Hello world!");
        sendSMS.setMessageType(MESSAGE_HIGH_QUALITY);
        sendSMS.addRecipient("+39123456789");
        // Send it in 5 minutes!
        sendSMS.setScheduledDeliveryTime(new Date(System.currentTimeMillis() + (60000L * 5L)));
        sendSMS(authKeys, sendSMS);
        }
        catch (Exception e) {
        e.printStackTrace();
        }
        }
        /*** This object is used to create an SMS message sending request.
        * The JSon object is then automatically created starting from an instance
        * of this class, using GSon.
        */
        public static class SendSMSRequest {
        /** The message body */
        private String message;
        /** The message type */
        private String message_type = MESSAGE_HIGH_QUALITY;
        /** Should the API return the remaining credits? */
        private boolean returnCredits = false;
        /** The list of recipients */
        private List<String> recipient = new ArrayList<>();
        /** The sender Alias (TPOA) */
        private String sender = null;
        /** Postpone the SMS message sending to the specified date */
        private Date scheduled_delivery_time = null;
        public String getMessage() {
        return message;
        }
        public void setMessage(String message) {
        this.message = message;
        }
        public String getMessageType() {
        return message_type;
        }
        public void setMessageType(String messageType) {
        this.message_type = messageType;
        }
        public boolean isReturnCredits() {
        return returnCredits;
        }
        public void setReturnCredits(boolean returnCredits) {
        this.returnCredits = returnCredits;
        }
        public List<String> getRecipient() {
        return recipient;
        }
        public String getSender() {
        return sender;
        }
        public void setSender(String sender) {
        this.sender = sender;
        }
        public Date getScheduledDeliveryTime() {
        return scheduled_delivery_time;
        }
        public void setScheduledDeliveryTime(Date scheduled_delivery_time) {
        this.scheduled_delivery_time = scheduled_delivery_time;
        }
        public void addRecipient(String recipient) {
        this.recipient.add(recipient);
        }
        }
        /**
        * This class represents the API Response. It is automatically created starting
        * from the JSON object returned by the server, using GSon
        */
        public static class SendSMSResponse {
        private String result;
        private String order_id;
        private int total_sent;
        private int remaining_credits;
        private String internal_order_id;
        public String getResult() {
        return result;
        }
        public String getOrderId() {
        return order_id;
        }
        public int getTotalSent() {
        return total_sent;
        }
        public int getRemainingCredits() {
        return remaining_credits;
        }
        public String getInternalOrderId() {
        return internal_order_id;
        }
        public boolean isValid() {
        return "OK".equals(result);
        }
        }
        /**
        * Authenticates the user given it's username and password.
        * Returns the pair user_key, Session_key
        * @param username The user username
        * @param password The user password
        * @return A list with 2 strings. Index 0 is the user_key, index 1 is the Session_key
        * @throws IOException If an error occurs
        */
        private static String[] login(String username, String password) throws IOException {
        URL url = new URL(BASEURL + "/login?username=" + username + "&password=" + password);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        if (conn.getResponseCode() != 200) {
        throw new RuntimeException("Failed : HTTP error code : "
        + conn.getResponseCode());
        }
        BufferedReader br =
        new BufferedReader(new InputStreamReader(conn.getInputStream()));
        String response = "";
        String output;
        while ((output = br.readLine()) != null) {
        response += output;
        }
        conn.disconnect();
        String[] parts = response.split(";");
        return parts;
    }

    /**
     * Sends an SMS message
     * @param authKeys The pair of user_key and Session_key
     * @param sendSMS The SendSMS object
     * @throws IOException If an error occurs
     */
    private static boolean sendSMS(String[] authKeys, SendSMSRequest sendSMS) throws IOException {
        GsonBuilder builder = new GsonBuilder();
        Gson gson = builder.create();

        URL url = new URL(BASEURL + "/sms");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();

        // Sending an SMS requires authentication
        conn.setRequestProperty("user_key", authKeys[0]);
        conn.setRequestProperty("Session_key", authKeys[1]);

        conn.setRequestMethod("POST");
        conn.setRequestProperty("Accept", "application/json");
        conn.setRequestProperty("Content-type", "application/json");
        conn.setDoOutput(true);

        String payload = gson.toJson(sendSMS);

        OutputStream os = conn.getOutputStream();
        os.write(payload.getBytes());
        os.flush();

        if (conn.getResponseCode() != 201) {
            throw new RuntimeException("Failed : HTTP error code : "
                                       + conn.getResponseCode());
        }

        BufferedReader br =
            new BufferedReader(new InputStreamReader(conn.getInputStream()));

        String response = "";
        String output;
        while ((output = br.readLine()) != null) {
            response += output;
        }
        conn.disconnect();

        SendSMSResponse responseObj = gson.fromJson(response, SendSMSResponse.class);

        return responseObj.isValid();
    }
}
<?php

define("BASEURL", "http://app.gateway.smsend.it/API/v1.0/REST/");

define("MESSAGE_HIGH_QUALITY", "N");
define("MESSAGE_MEDIUM_QUALITY", "L");
define("MESSAGE_LOW_QUALITY", "LL");

/**
 * Authenticates the user given it's username and password.
 * Returns the pair user_key, Session_key
 */
function login($username, $password) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, BASEURL .
                'login?username=' . $username .
                '&password=' . $password);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close($ch);

    if ($info['http_code'] != 200) {
        return null;
    }

    return explode(";", $response);
}

/**
 * Sends an SMS message
 */
function sendSMS($auth, $sendSMS) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, BASEURL . 'sms');
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-type: application/json',
        'user_key: ' . $auth[0],
        'Session_key: ' . $auth[1]
    ));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($sendSMS));
    $response = curl_exec($ch);
    $info = curl_getinfo($ch);
    curl_close($ch);

    if ($info['http_code'] != 201) {
        return null;
    }

    return json_decode($response);
}

$auth = login('username', 'password');

$smsSent = sendSMS($auth, array(
    "message" => "Hello world!",
    "message_type" => MESSAGE_HIGH_QUALITY,
    "returnCredits" => false,
    "recipient" => array("+349123456789"),
    "sender" => null,     // Place here a custom sender if desired
    "scheduled_delivery_time" => date('YmdHi', strtotime("+5 minutes")), // postpone by 5 minutes
));

if ($smsSent->result == "OK") {
    echo 'SMS sent!';
}

?>
# pip install requests
import requests
import json
import sys
import datetime

BASEURL = "http://app.gateway.smsend.it/API/v1.0/REST/"

MESSAGE_HIGH_QUALITY = "N"
MESSAGE_MEDIUM_QUALITY = "L"
MESSAGE_LOW_QUALITY = "LL"


def json_serial(obj):
    """JSON serializer for objects not serializable by default json code"""

    if isinstance(obj, datetime.datetime):
        serial = obj.isoformat()
        return serial

    raise TypeError ("Type not serializable")


def login(username, password):
    """Authenticates the user given it's username and password. Returns a
    couple (user_key, session_key)
    """

    r = requests.get("%slogin?username=%s&password=%s"
                     % (BASEURL, username, password))

    if r.status_code != 200:
        return None

    user_key, session_key = r.text.split(';')
    return user_key, session_key


def sendSMS(auth, sendsms):
    """Sends an SMS"""

    headers = { 'user_key': auth[0],
                'Session_key': auth[1],
                'Content-type' : 'application/json' }

    r = requests.post("%ssms" % BASEURL,
                      headers=headers,
                      data=json.dumps(sendsms, default=json_serial))

    if r.status_code != 201:
        return None

    return json.loads(r.text)


if __name__ == "__main__":
    auth = login("username", "password")

    if not auth:
        print("Unable to login..")
        sys.exit(-1)

    sentSMS = sendSMS(auth,
                      {
                          "message" : "Hello world!",
                          "message_type" : MESSAGE_HIGH_QUALITY,
                          "returnCredits" : False,
                          "recipient": ["+349123456789",],

                          # Place here a custom sender if desired
                          "sender": None,

                          # Postpone the SMS sending by 5 minutes
                          "scheduled_delivery_time" : (datetime.datetime.now() +
                                                       datetime.timedelta(minutes=5))
                      })

    if sentSMS['result'] == "OK":
        print("SMS sent!")
var BASEURL = 'http://app.gateway.smsend.it/API/v1.0/REST/';

var MESSAGE_HIGH_QUALITY = "N";
var MESSAGE_MEDIUM_QUALITY = "L";
var MESSAGE_LOW_QUALITY = "LL";

var request = require('request');

/**
 * Authenticates the user given it's username and password.  Callback
 * is called when completed. If error is false, then an authentication
 * object is passed to the callback as second parameter.
 */
function login(username, password, callback) {
    request({
        url: BASEURL + 'login?username=' + username + '&password=' + password,
        method: 'GET',
        callback: function (error, responseMeta, response) {
            if (!error && responseMeta.statusCode == 200) {
                var auth = response.split(';');
                callback(error, {
                    user_key : auth[0],
                    session_key : auth[1]
                });
            }
            else {
                callback(error);
            }
        }
    });
}

/**
 * Sends an SMS message
 */
function sendSMS(auth, sendsms, callback) {
    request({
        url: BASEURL + 'sms',
        method: 'POST',
        headers: { 'user_key' : auth.user_key, 'Session_key' : auth.session_key },
        json: true,
        body:  sendsms,

        callback: function (error, responseMeta, response) {
            if (!error && responseMeta.statusCode == 201) {
                callback(response.result !== 'OK', response);
            }
            else {
                callback(false);
            }
        }
    });
}

var smsData = {
    "returnCredits": true,
    "recipient": [
        "+393471234567",
        "+393471234568"
    ],
    "scheduled_delivery_time": "20171223101010",
    "message": "Hello world!",
    "message_type": MESSAGE_HIGH_QUALITY
}

login('username', 'password',
      function(error, auth) {
          if (!error) {
              sendSMS(auth, smsData,
                      function(error, data) {
                          if (error) {
                              console.log("An error occurred");
                          }
                          else {
                              console.log("SMS Sent!");
                          }
                      });
          }
    else {
              console.log("Unable to login");
          }
      });

require 'net/http'
require 'uri'
require 'json'

BASEURL = "http://app.gateway.smsend.it/API/v1.0/REST/"

MESSAGE_HIGH_QUALITY = "N"
MESSAGE_MEDIUM_QUALITY = "L"
MESSAGE_LOW_QUALITY = "LL"

# Authenticates the user given it's username and password. Returns a
# couple (user_key, session_key)
def login(username, password)
  uri = URI.parse(BASEURL + "login?username=" + username  + "&password=" + password)

  # Create the HTTP objects
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(uri.request_uri)
  request['Content-type'] = 'application/json'

  # Send the request
  responseData = http.request(request)
  if responseData.code == "200"
    return responseData.body.split(';')
  end

  return None
end

# Sends an SMS
def sendSMS(auth, sendSMS)
  uri = URI.parse(BASEURL + "sms")

  # Create the HTTP objects
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.request_uri)
  request['Content-type'] = 'application/json'
  request['user_key'] = auth[0]
  request['Session_key'] = auth[1]
  request.body = sendSMS.to_json

  # Send the request
  responseData = http.request(request)
  if responseData.code == "201"
    return JSON.parse(responseData.body)
  else
    return None
  end
end

####################
# Main

auth = login('username', 'password')

if not auth
  puts "Unable to login"
else
  response = sendSMS(auth,
                     {
                      "returnCredits": true,
                      "recipient": [
                                     "+393471234567",
                                     "+393471234568"
                                   ],
                      "message": "Hello world!",
                      "message_type": MESSAGE_HIGH_QUALITY,
                     })
  if response['result'] == 'OK'
    puts "SMS Sent!"
  else
    puts "An error occurred"
  end
end
using System;
using System.Text;
using System.Net;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 *
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {

        public static String BASEURL = "http://app.gateway.smsend.it/API/v1.0/REST/";

        public static String MESSAGE_HIGH_QUALITY = "N";
        public static String MESSAGE_MEDIUM_QUALITY = "L";
        public static String MESSAGE_LOW_QUALITY = "LL";

        static void Main(string[] args)
        {

            String[] auth = authenticate("username", "password");

            SendSMS sendSMSRequest = new SendSMS();

            sendSMSRequest.message = "Hello World!";
            sendSMSRequest.message_type = MESSAGE_HIGH_QUALITY;
            sendSMSRequest.recipient = new String[] {"+39349123456789"};

            // Send the SMS message at the given date (Optional)
            sendSMSRequest.scheduled_delivery_time = new DateTime(2017, 8, 18, 13, 31, 00);

            SMSSent smsSent = sendSMS(auth, sendSMSRequest);

            if ("OK".Equals(smsSent.result)) {
                Console.WriteLine("SMS successfully sent!");
            }
        }


        /**
         * Authenticates the user given it's username and
         * password. Returns a couple (user_key, session_key)
         */
        static String[] authenticate(String username, String password)
        {
            String[] auth = null;

            using (var wb = new WebClient())
            {
                var response = wb.DownloadString(BASEURL +
                                                 "login?username=" + username +
                                                 "&password=" + password);
                auth = response.Split(';');
            }

            return auth;
        }


        /**
         * Sends an SMS
         */
        static SMSSent sendSMS(String[] auth, SendSMS sendSMS)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", auth[0]);
                wb.Headers.Add("Session_key", auth[1]);

                String json = JsonConvert.SerializeObject(sendSMS);

                var sentSMSBody =
                    wb.UploadString(BASEURL + "sms", "POST", json);

                SMSSent sentSMSResponse =
                    JsonConvert.DeserializeObject<SMSSent>(sentSMSBody);

               return sentSMSResponse;
            }
        }
    }

    /**
     * This object is used to create an SMS message sending request.
     * The JSon object is then automatically created starting from an
     * instance of this class, using JSON.NET.
     */
    class SendSMS
    {
        /** The message body */
        public String message;

        /** The message type */
        public String message_type;

        /** The sender Alias (TPOA) */
        public String sender;

        /** Postpone the SMS message sending to the specified date */
        public DateTime? scheduled_delivery_time;

        /** The list of recipients */
        public String[] recipient;

        /** Should the API return the remaining credits? */
        public Boolean returnCredits = false;
    }


    /**
     * This class represents the API Response. It is automatically created starting
     * from the JSON object returned by the server, using GSon
     */
    class SMSSent
    {
        /** The result of the SMS message sending */
        public String result;

        /** The order ID of the SMS message sending */
        public String order_id;

        /** The actual number of sent SMS messages */
        public int total_sent;

        /** The remaining credits */
        public int remaining_credits;
    }

}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

use constant BASEURL => "http://app.gateway.smsend.it/API/v1.0/REST/";
use constant MESSAGE_HIGH_QUALITY => "N";
use constant MESSAGE_MEDIUM_QUALITY => "L";
use constant MESSAGE_LOW_QUALITY => "LL";

sub authenticate($$$) {
    my ($ua, $username, $password) = @_;

    my $server_endpoint = BASEURL . "login?username=$username&password=$password";

    my $req = HTTP::Request->new(GET => $server_endpoint);
    $req->header('Content-type' => 'application/json');

    my $resp = $ua->request($req);
    if ($resp->is_success && $resp->code == 200) {
        my $response = $resp->decoded_content;

        my ($user_key, $session_key) = $response =~ /(.*);(.*)/;

        return [$user_key, $session_key];
    }
}

sub send_sms($$$) {
    my ($ua, $auth, $sendsms) = @_;

    my $server_endpoint = BASEURL . "sms";

    my $req = HTTP::Request->new(POST => $server_endpoint);

    # IMPORTANT: Not adding the ':' before 'user_key' and
    # 'Session_key' will result in perl to automatically rewrite the
    # headers as 'User-Key' and 'Session-Key', which is not supported
    # by our API.
    $req->header('Content_type' => 'application/json',
                 ':user_key' => $auth->[0],
                 ':Session_key' => $auth->[1]);

    $req->content(to_json($sendsms));

    my $resp = $ua->request($req);
    if ($resp->is_success) {
        return from_json($resp->decoded_content);
    }
}

my $ua = LWP::UserAgent->new;

my $auth = authenticate($ua, "username", "password");

die ("Unable to authenticate\n") unless ($auth);

my $sendsms = {
    "message" => "Hello world!",
    "message_type" => MESSAGE_HIGH_QUALITY,
    "recipient" => ["+39349123456789"],
};

my $smssent = send_sms($ua, $auth, $sendsms);

print "SMS successfully sent!\n" if ($smssent->{"result"} eq "OK");

You can start by copying this example and you’ll be up and running for sending an SMS message to multiple recipients in just a few clicks!

Just change the username and password strings, add a valid recipient list and execute the code!

The listed example authenticates the user using username and password with the Authentication API and then sends an SMS calling the Send SMS API.

Authentication API

Authentication methods

The following are the two available methods to authenticate a user, given a username and a password (registration required):

In both cases, the returned user_key, as well as the session key or the token, are required to be provided in the HTTP request headers in order to perform any API call after the login.

Authenticate using a session key

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}' -H 'Content-Type: application/json'  

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}' -H 'Content-Type: application/json'  
# pip install requests
import requests
import json


r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}")

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text
    user_key, session_key = response.split(';')
    print("user_key: " + user_key)
    print("Session_key: " + session_key)

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            String[] parts = response.split(";");
            String user_key = parts[0];
            String session_key = parts[1];
            System.out.println("user_key: " + user_key);
            System.out.println("Session_key: " + session_key);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    $values = explode(";", $response);
    echo('user_key: ' . $values[0]);
    echo('Session_key: ' . $values[1]);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}',
    method: 'GET',
    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            var arr = response.split(';');
            console.log("user_key: " + arr[0]);
            console.log("Session_key: " + arr[1]);
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'


# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  user_key, session_key = response.split(';')
  puts "user_key: " + user_key
  puts "Session_key: " + session_key
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}");
                String[] auth = response.Split(';');
                Console.WriteLine("user_key: " + auth[0]);
                Console.WriteLine("Session_key: " + auth[1]);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/login?username={username}&password={password}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my ($user_key, $session_key) = $response =~ /(.*);(.*)/;
  print "user_key: $user_key\n";
  print "Session_key: $session_key\n";
}

On success, the above command returns the following response:

{USER_KEY};{SESSION_KEY}

Where {USER_KEY} is the user key and {SESSION_KEY} is the session key

The login with session key API lets you authenticate by using your username and password, and returns a token to be used for authenticating the next API calls. The following HTTP headers should be provided after the login:

user_key:{USER_KEY}

Session_key:{SESSION_KEY}

Where {USER_KEY} and {SESSION_KEY} are the values returned by the login API.

HTTP Request

GET /API/v1.0/REST/login?username={USERNAME}&password={PASSWORD}

Parameters

Parameter Type Description Required Default
username String Your account’s username Yes -
password String Your account’s password Yes -

Returns

Code Description
200 The user_key and the session_key
404 [Not found] Credentials are incorrect
400 Other errors, details are in the body

Authenticate using a user token

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}' -H 'Content-Type: application/json'  

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}' -H 'Content-Type: application/json'  
# pip install requests
import requests
import json


r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}")

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text
    user_key, access_token = response.split(';')
    print("user_key: " + user_key)
    print("Access_token: " + access_token)

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            String[] parts = response.split(";");
            String user_key = parts[0];
            String access_token = parts[1];
            System.out.println("user_key: " + user_key);
            System.out.println("Access_token: " + access_token);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    $values = explode(";", $response);
    echo('user_key: ' . $values[0]);
    echo('Access_token: ' . $values[1]);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}',
    method: 'GET',
    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            var arr = response.split(';');
            console.log("user_key: " + arr[0]);
            console.log("Access_token: " + arr[1]);
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'


# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  user_key, access_token = response.split(';')
  puts "user_key: " + user_key
  puts "Access_token: " + access_token
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}");
                String[] auth = response.Split(';');
                Console.WriteLine("user_key: " + auth[0]);
                Console.WriteLine("Access_token: " + auth[1]);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/token?username={username}&password={password}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my ($user_key, $access_token) = $response =~ /(.*);(.*)/;
  print "user_key: $user_key\n";
  print "Access_token: $access_token\n";
}

On success, the above command returns the following response:

{USER_KEY};{ACCESS_TOKEN}

Where {USER_KEY} is the user key and {ACCESS_TOKEN} is the access token

The login with token API lets you authenticate by using your username and password, and returns a token to be used for authenticating the next API calls. The following HTTP headers should be provided after the login:

user_key:{USER_KEY}

Access_token:{ACCESS_TOKEN}

Where {USER_KEY} and {ACCESS_TOKEN} are the values returned by the login API.

HTTP Request

GET /API/v1.0/REST/token?username={USERNAME}&password={PASSWORD}

Parameters

Parameter Type Description Required Default
username String Your account’s username Yes -
password String Your account’s password Yes -

Returns

Code Description
200 The user_key and the access token
404 [Not found] Credentials are incorrect
400 Other errors, details are in the body

User API

The following are utility functions regarding the Authenticated User (e.g. the user status, password reset, etc)

Dashboard

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/dashboard' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/dashboard' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/dashboard", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text
    print(response)

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/dashboard");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            System.out.println(response);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/dashboard');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo($response);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/dashboard',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log(response);
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/dashboard")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts response
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/dashboard");
                Console.WriteLine(response);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/dashboard";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

http://app.gateway.smsend.it/API/v1.0/REST//s/user/external-auth?k=07366A25DF70038A22B9D284AB13E856BD95C6227&action=FC07AD201AE372F378&action-params=7010AB

API used to retrieve the dashboard URL of the authenticated user

HTTP Request

GET /API/v1.0/REST/dashboard

Returns

Code Description
200 Returns the URL for the user’s dashboard
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
400 Other errors, details are in the body

Verify session

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/checksession' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/checksession' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/checksession", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text
    print("Is session valid: " + str(response == "true"))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/checksession");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            System.out.println("Is session valid: " + ("true".equals(response)));
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/checksession');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Is session valid: ' . ($response === "true"));
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/checksession',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Is session valid: ' + (response == "true"));
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/checksession")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Is session valid " + response
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/checksession");
                Console.WriteLine("Is session valid: " + response);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/checksession";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

"true" or "false"

Checks whether the user session is still active and valid (without renewal).

HTTP Request

GET /API/v1.0/REST/checksession

Returns

Code Description
200 String “true” if the session is valid, “false” otherwise.
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
400 Other errors, details are in the body

Reset password

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text
    print("Password changed: " + str(response == "true"))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            System.out.println("Password changed: " + ("true".equals(response)));
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Password changed: ' . ($response === "true"));
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Password changed: ' + (response == "true"));
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Password changed " + response
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}", "POST", null)
                Console.WriteLine("Password changed: " + response);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/pwdreset?password={newpwd}";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

"true" or "false"

Changes the authenticated user’s password

HTTP Request

POST /API/v1.0/REST/pwdreset?password={PWD}

Parameters

Parameter Type Description Required Default
password String The new user password Yes -

Returns

Code Description
200 String “true” on success, “false” otherwise
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] User key does not exist

User status

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/status' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/status' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/status", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/status");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/status');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/status',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/status")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/status");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/status";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "money": null, 
    "sms": [
        {
            "type": "SI", 
            "quantity": 16079
        }, 
        {
            "type": "GS", 
            "quantity": 11815
        }, 
        {
            "type": "GP", 
            "quantity": 10407
        }, 
        {
            "type": "EE", 
            "quantity": 10387
        }
    ], 
    "email": {
        "bandwidth": 2000.0, 
        "purchased": "2015-01-16", 
        "billing": "EMAILPERHOUR", 
        "expiry": "2016-01-17"
    }, 
    "landing": null
}

Used to retrieve the services status of the user identified by the id.

HTTP Request

GET /API/v1.0/REST/status?getMoney={value}

Parameters

Parameter Type Description Required Default
getMoney String “true” or “false” Add user current money to response No “false”

Returns

Code Description
200 A Json object representing the user status
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] Credentials are incorrect

Contacts API

This part of the API is used to manage contacts. A contact can be used both in SMS and Email sending, provided that a phone number and/or an email address are given.

Add a contact

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/contact' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONENUMBER}", 
    "name": "{NAME}", 
    "surname": "{SURNAME}", 
    "gender": "{GENDER}", 
    "fax": "{FAX}", 
    "zip": "{ZIP}", 
    "address": "{ADDRESS}", 
    "city": "{CITY}", 
    "province": "{PROVINCE}", 
    "birthdate": "{BIRTHDATE}", 
    "groupIds": [
        "{GRP1}", 
        "{GRP2}"
    ]
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/contact' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONENUMBER}", 
    "name": "{NAME}", 
    "surname": "{SURNAME}", 
    "gender": "{GENDER}", 
    "fax": "{FAX}", 
    "zip": "{ZIP}", 
    "address": "{ADDRESS}", 
    "city": "{CITY}", 
    "province": "{PROVINCE}", 
    "birthdate": "{BIRTHDATE}", 
    "groupIds": [
        "{GRP1}", 
        "{GRP2}"
    ]
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONENUMBER}", 
    "name": "{NAME}", 
    "surname": "{SURNAME}", 
    "gender": "{GENDER}", 
    "fax": "{FAX}", 
    "zip": "{ZIP}", 
    "address": "{ADDRESS}", 
    "city": "{CITY}", 
    "province": "{PROVINCE}", 
    "birthdate": "{BIRTHDATE}", 
    "groupIds": [
        "{GRP1}", 
        "{GRP2}"
    ]
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/contact", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/contact");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"email\": \"{EMAIL}\", " + 
              "    \"phoneNumber\": \"{PHONENUMBER}\", " + 
              "    \"name\": \"{NAME}\", " + 
              "    \"surname\": \"{SURNAME}\", " + 
              "    \"gender\": \"{GENDER}\", " + 
              "    \"fax\": \"{FAX}\", " + 
              "    \"zip\": \"{ZIP}\", " + 
              "    \"address\": \"{ADDRESS}\", " + 
              "    \"city\": \"{CITY}\", " + 
              "    \"province\": \"{PROVINCE}\", " + 
              "    \"birthdate\": \"{BIRTHDATE}\", " + 
              "    \"groupIds\": [" + 
              "        \"{GRP1}\", " + 
              "        \"{GRP2}\"" + 
              "    ]" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "email": "{EMAIL}", ' . 
  '    "phoneNumber": "{PHONENUMBER}", ' . 
  '    "name": "{NAME}", ' . 
  '    "surname": "{SURNAME}", ' . 
  '    "gender": "{GENDER}", ' . 
  '    "fax": "{FAX}", ' . 
  '    "zip": "{ZIP}", ' . 
  '    "address": "{ADDRESS}", ' . 
  '    "city": "{CITY}", ' . 
  '    "province": "{PROVINCE}", ' . 
  '    "birthdate": "{BIRTHDATE}", ' . 
  '    "groupIds": [' . 
  '        "{GRP1}", ' . 
  '        "{GRP2}"' . 
  '    ]' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/contact');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/contact',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "email": "{EMAIL}", 
        "phoneNumber": "{PHONENUMBER}", 
        "name": "{NAME}", 
        "surname": "{SURNAME}", 
        "gender": "{GENDER}", 
        "fax": "{FAX}", 
        "zip": "{ZIP}", 
        "address": "{ADDRESS}", 
        "city": "{CITY}", 
        "province": "{PROVINCE}", 
        "birthdate": "{BIRTHDATE}", 
        "groupIds": [
            "{GRP1}", 
            "{GRP2}"
        ]
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/contact")
payload =     {
        "email": "{EMAIL}", 
        "phoneNumber": "{PHONENUMBER}", 
        "name": "{NAME}", 
        "surname": "{SURNAME}", 
        "gender": "{GENDER}", 
        "fax": "{FAX}", 
        "zip": "{ZIP}", 
        "address": "{ADDRESS}", 
        "city": "{CITY}", 
        "province": "{PROVINCE}", 
        "birthdate": "{BIRTHDATE}", 
        "groupIds": [
            "{GRP1}", 
            "{GRP2}"
        ]
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"email\": \"{EMAIL}\", " + 
                  "    \"phoneNumber\": \"{PHONENUMBER}\", " + 
                  "    \"name\": \"{NAME}\", " + 
                  "    \"surname\": \"{SURNAME}\", " + 
                  "    \"gender\": \"{GENDER}\", " + 
                  "    \"fax\": \"{FAX}\", " + 
                  "    \"zip\": \"{ZIP}\", " + 
                  "    \"address\": \"{ADDRESS}\", " + 
                  "    \"city\": \"{CITY}\", " + 
                  "    \"province\": \"{PROVINCE}\", " + 
                  "    \"birthdate\": \"{BIRTHDATE}\", " + 
                  "    \"groupIds\": [" + 
                  "        \"{GRP1}\", " + 
                  "        \"{GRP2}\"" + 
                  "    ]" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/contact", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/contact";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "email" => "{EMAIL}", 
    "phoneNumber" => "{PHONENUMBER}", 
    "name" => "{NAME}", 
    "surname" => "{SURNAME}", 
    "gender" => "{GENDER}", 
    "fax" => "{FAX}", 
    "zip" => "{ZIP}", 
    "address" => "{ADDRESS}", 
    "city" => "{CITY}", 
    "province" => "{PROVINCE}", 
    "birthdate" => "{BIRTHDATE}", 
    "groupIds" => [
        "{GRP1}", 
        "{GRP2}"
    ]
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the created contact:
'Location': '/contact/AVvZEwZHHnl8wUZve6CT'

Add a contact to the user’s addressbook.

HTTP Request

POST /API/v1.0/REST/contact

Body Fields

Parameter Type Description Required Default
email String (A valid email) The email of the contact Yes -
phoneNumber String (A non empty string) The phone number of the contact No “”
name String (max 40 chars) The first name of the contact No “”
surname String (max 40 chars) The last name of the contact No “”
gender String (“m” or “f”) The gender of the contact No “”
fax String (max 32 chars) The Fax number of the contact No “”
address String (max 256 chars) The address of the contact No “”
city String (max 32 chars) The city of the contact No “”
province String (max 32 chars) The province of the contact No “”
birthdate String [ddMMyy, yyyyMMdd, ddMMyyHHmm, yyyyMMddHHmmss, yyyy-MM-dd HH:mm, yyyy-MM-dd HH:mm.0] The birth date of the contact No “”
zip String (max 16 chars) The ZIP code of the contact No “”
groupIds List(String) The groups (Ids) in which the contact will be added No []

Returns

Code Description
201 Empty string, and the HTTP Location header containing the path of the newly created contact
400 Campaign not active or not found, no email provided, group not owned or a generic error. Details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Get a contact

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/contact/{contactid}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
   "email":"alessandro.magno@macedonia.com",
   "phoneNumber":"+39349123456789",
   "name": "Alessandro",
   "surname": "Magno",
   "groupIds":[ ],
   "gender":"m",
   "fax":null,
   "address":null,
   "city":null,
   "province":null,
   "birthdate":"2017-05-11",
   "zip":null
}

Get a contact’s details

HTTP Request

GET /API/v1.0/REST/contact/{contactid}

Parameters

Parameter Type Description Required Default
contactid String The contact ID Yes -

Returns

Code Description
200 The contact’s details
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The given contactid was not found

Registration of a contact to a list

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONE_NUMBER}"
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONE_NUMBER}"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "email": "{EMAIL}", 
    "phoneNumber": "{PHONE_NUMBER}"
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"email\": \"{EMAIL}\", " + 
              "    \"phoneNumber\": \"{PHONE_NUMBER}\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "email": "{EMAIL}", ' . 
  '    "phoneNumber": "{PHONE_NUMBER}"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "email": "{EMAIL}", 
        "phoneNumber": "{PHONE_NUMBER}"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact")
payload =     {
        "email": "{EMAIL}", 
        "phoneNumber": "{PHONE_NUMBER}"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"email\": \"{EMAIL}\", " + 
                  "    \"phoneNumber\": \"{PHONE_NUMBER}\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/list/{campaign_id}/contact";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "email" => "{EMAIL}", 
    "phoneNumber" => "{PHONE_NUMBER}"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

"" 

Creates a new contact entry and adds it onto the specified campaign.

HTTP Request

POST /API/v1.0/REST/list/{campaign_id}/contact?SendOptIn={value}

Parameters

Parameter Type Description Required Default
campaign_id Int The campaign in which the contact will be added Yes -
SendOptIn String, “true” or “false” Send an Opt-In email to the contact’s email No “false”

Body Fields

Parameter Type Description Required Default
email String The email of the contact Yes -
phoneNumber String The phone number of the contact No “”
name String The first name of the contact No “”
surname String The last name of the contact No “”
gender String The gender of the contact No “”
fax String The Fax number of the contact No “”
address String The address of the contact No “”
city String The city of the contact No “”
province String The province of the contact No “”
birthdate String [ddMMyy, yyyyMMdd, ddMMyyHHmm, yyyyMMddHHmmss, yyyy-MM-dd HH:mm, yyyy-MM-dd HH:mm.0] The birth date of the contact No “”
zip String The ZIP code of the contact No “”
groupIds List(String) The groups (Ids) in which the contact will be added No []

Returns

Code Description
201 The contact has been added and the HTTP Location Header returns its URL.
400 Campaign not active or not found, no email provided, group not owned or a generic error. Details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Contacts groups API

This section describes how groups of contacts are created, updated and deleted. SMS messages and emails can be directly sent to groups of contacts.

Create a contacts group

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/group' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/group' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/group", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/group");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"name\": \"{NAME}\", " + 
              "    \"description\": \"{DESCRIPTION}\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "name": "{NAME}", ' . 
  '    "description": "{DESCRIPTION}"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/group');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/group',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "name": "{NAME}", 
        "description": "{DESCRIPTION}"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/group")
payload =     {
        "name": "{NAME}", 
        "description": "{DESCRIPTION}"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"name\": \"{NAME}\", " + 
                  "    \"description\": \"{DESCRIPTION}\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/group", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/group";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "name" => "{NAME}", 
    "description" => "{DESCRIPTION}"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the created group:
'Location': '/group/{group_id}'

Creates an empty group of contacts given a name and a description.

HTTP Request

POST /API/v1.0/REST/group

Body Fields

Parameter Type Description Required Default
name String The name of the group Yes -
description String The description of the group Yes -

Returns

Code Description
201 An empty string, and the HTTP Location header containing the path to the newly created group
400 If the group name is invalid, or other errors, with a code error
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] If the requesting user does not exist.

Modify an existing contacts group

# Session Key example
curl -XPUT 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}
'

# Access token example
curl -XPUT 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "name": "{NAME}", 
    "description": "{DESCRIPTION}"
}"""

r = requests.put("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}", headers=headers, data=payload)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("PUT");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"name\": \"{NAME}\", " + 
              "    \"description\": \"{DESCRIPTION}\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "name": "{NAME}", ' . 
  '    "description": "{DESCRIPTION}"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}',
    method: 'PUT',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "name": "{NAME}", 
        "description": "{DESCRIPTION}"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}")
payload =     {
        "name": "{NAME}", 
        "description": "{DESCRIPTION}"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Put.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"name\": \"{NAME}\", " + 
                  "    \"description\": \"{DESCRIPTION}\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}", "PUT", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}";

my $req = HTTP::Request->new(PUT => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "name" => "{NAME}", 
    "description" => "{DESCRIPTION}"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the modified group:
'Location': '/group/{group_id}'

Updates a given contacts group

HTTP Request

PUT /API/v1.0/REST/group/{group_id}

Body Fields

Parameter Type Description Required Default
name String The name of the group Yes -
description String The description of the group Yes -

Returns

Code Description
200 An empty string, and the HTTP Location header containing the path to the updated group
400 If the given group_id is invalid, if the address book is locked, if the group name is invalid, or other errors, with a code error
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] If the requesting user does not exist.

Delete a contacts group

# Session Key example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.delete("http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("DELETE");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}',
    method: 'DELETE',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                wb.UploadValues("http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}", "DELETE", new NameValueCollection());
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/group/{groupid}";

my $req = HTTP::Request->new(DELETE => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

"" 

Deletes the contacts group identified by the given ID.

HTTP Request

GET /API/v1.0/REST/group/{group_id}?deletecontacts={del}

Parameters

Parameter Type Description Required Default
group_id Int The group ID to be deleted Yes -
deletecontacts String “true” or “false” If “true”, also deletes all contacts in the group No “false”

Returns

Code Description
200 An empty string
400 If the given group_id is invalid, if the address book is locked, if the group name is invalid, or other errors, with a code error
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] Credentials are incorrect

List contacts groups

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/groups' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/groups' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/groups", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/groups");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/groups');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/groups',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/groups")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/groups");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/groups";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
 "groups":[                         "// The list of groups"
  {
    "id_group": (string),           "// The ID of a group in the list"
    "group_name": (string),         "// The group name"
    "group_description": (string)   "// The group description"
  },
  {...}                             "// Other groups in the list (omitted..)"
 ],
 "pageNumber": (int),               "// Paging: The page number"
 "pageSize": (int),                 "// Paging: The page size"
 "Total": (int)                     "// Paging: The total number of groups"
}

Returns the list of existing contacts groups, paginated.

HTTP Request

GET /API/v1.0/REST/groups?pageNumber={page}&pageSize={size}

Parameters

Parameter Type Description Required Default
pageNumber int The page number No 1
pageSize int The page size No 5

Returns

Code Description
200 The paginated list of contacts groups, as a Json Object
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Add a contact to a group

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}", "POST", null)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the contact:
'Location': '/contact/{contact_id}'

Adds the specified contact in the specified contacts group.

HTTP Request

POST /API/v1.0/REST/group/{group_id}/contact/{contact_id}

Parameters

Parameter Type Description Required Default
group_id Int The Contacts Group ID Yes -
contact_id Int The Contact ID Yes -

Returns

Code Description
200 An empty string, and the HTTP Location header containing the URL of the contact
400 If contact_id is invalid, if the addressbook is locked or other. Details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Remove a contact from a group

# Session Key example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.delete("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("DELETE");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}',
    method: 'DELETE',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                wb.UploadValues("http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}", "DELETE", new NameValueCollection());
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/group/{group_id}/contact/{contact_id}";

my $req = HTTP::Request->new(DELETE => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the contact:
'Location': '/contact/{contact_id}'

Removes the specified contact from the specified contacts group.

HTTP Request

DELETE /API/v1.0/REST/group/{group_id}/contact/{contact_id}

Parameters

Parameter Type Description Required Default
group_id Int The Contacts Group ID Yes -
contact_id Int The Contact ID Yes -

Returns

Code Description
200 An empty string, and the HTTP Location header containing the URL of the contact
400 If contact_id is invalid, if the addressbook is locked or other. Details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

TPOA API

The TPOA (Transmission Path Originating Address) API is used to deal with TPOA entries (i.e. “SMS Sender aliases”) of the user.

Create a new alias

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/alias' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "alias": {
        "alias": "MY ALIAS", 
        "company-name": "company name", 
        "contact-name": "name", 
        "contact-surname": "surname", 
        "cod-fiscale": "02367940224", 
        "vat-number": "02367940224", 
        "contact-address": "address", 
        "contact-city": "city", 
        "contact-pcode": "pcode", 
        "contact-type": "WEB", 
        "contact-info": "www.www.it"
    }
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/alias' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "alias": {
        "alias": "MY ALIAS", 
        "company-name": "company name", 
        "contact-name": "name", 
        "contact-surname": "surname", 
        "cod-fiscale": "02367940224", 
        "vat-number": "02367940224", 
        "contact-address": "address", 
        "contact-city": "city", 
        "contact-pcode": "pcode", 
        "contact-type": "WEB", 
        "contact-info": "www.www.it"
    }
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "alias": {
        "alias": "MY ALIAS", 
        "company-name": "company name", 
        "contact-name": "name", 
        "contact-surname": "surname", 
        "cod-fiscale": "02367940224", 
        "vat-number": "02367940224", 
        "contact-address": "address", 
        "contact-city": "city", 
        "contact-pcode": "pcode", 
        "contact-type": "WEB", 
        "contact-info": "www.www.it"
    }
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/alias", headers=headers, data=payload)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/alias");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"alias\": {" + 
              "        \"alias\": \"MY ALIAS\", " + 
              "        \"company-name\": \"company name\", " + 
              "        \"contact-name\": \"name\", " + 
              "        \"contact-surname\": \"surname\", " + 
              "        \"cod-fiscale\": \"02367940224\", " + 
              "        \"vat-number\": \"02367940224\", " + 
              "        \"contact-address\": \"address\", " + 
              "        \"contact-city\": \"city\", " + 
              "        \"contact-pcode\": \"pcode\", " + 
              "        \"contact-type\": \"WEB\", " + 
              "        \"contact-info\": \"www.www.it\"" + 
              "    }" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "alias": {' . 
  '        "alias": "MY ALIAS", ' . 
  '        "company-name": "company name", ' . 
  '        "contact-name": "name", ' . 
  '        "contact-surname": "surname", ' . 
  '        "cod-fiscale": "02367940224", ' . 
  '        "vat-number": "02367940224", ' . 
  '        "contact-address": "address", ' . 
  '        "contact-city": "city", ' . 
  '        "contact-pcode": "pcode", ' . 
  '        "contact-type": "WEB", ' . 
  '        "contact-info": "www.www.it"' . 
  '    }' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/alias');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/alias',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "alias": {
            "alias": "MY ALIAS", 
            "company-name": "company name", 
            "contact-name": "name", 
            "contact-surname": "surname", 
            "cod-fiscale": "02367940224", 
            "vat-number": "02367940224", 
            "contact-address": "address", 
            "contact-city": "city", 
            "contact-pcode": "pcode", 
            "contact-type": "WEB", 
            "contact-info": "www.www.it"
        }
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/alias")
payload =     {
        "alias": {
            "alias": "MY ALIAS", 
            "company-name": "company name", 
            "contact-name": "name", 
            "contact-surname": "surname", 
            "cod-fiscale": "02367940224", 
            "vat-number": "02367940224", 
            "contact-address": "address", 
            "contact-city": "city", 
            "contact-pcode": "pcode", 
            "contact-type": "WEB", 
            "contact-info": "www.www.it"
        }
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"alias\": {" + 
                  "        \"alias\": \"MY ALIAS\", " + 
                  "        \"company-name\": \"company name\", " + 
                  "        \"contact-name\": \"name\", " + 
                  "        \"contact-surname\": \"surname\", " + 
                  "        \"cod-fiscale\": \"02367940224\", " + 
                  "        \"vat-number\": \"02367940224\", " + 
                  "        \"contact-address\": \"address\", " + 
                  "        \"contact-city\": \"city\", " + 
                  "        \"contact-pcode\": \"pcode\", " + 
                  "        \"contact-type\": \"WEB\", " + 
                  "        \"contact-info\": \"www.www.it\"" + 
                  "    }" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/alias", "POST", payload)

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/alias";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "alias" => {
        "alias" => "MY ALIAS", 
        "company-name" => "company name", 
        "contact-name" => "name", 
        "contact-surname" => "surname", 
        "cod-fiscale" => "02367940224", 
        "vat-number" => "02367940224", 
        "contact-address" => "address", 
        "contact-city" => "city", 
        "contact-pcode" => "pcode", 
        "contact-type" => "WEB", 
        "contact-info" => "www.www.it"
    }
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response, plus the HTTP Location header pointing to the created alias

{
  "result": "OK"
}

If getAlias is true instead, the following is returned:

{
    "result": "OK",
    "string": "MY ALIAS"
}

Creates a new TPOA Alias.

HTTP Request

POST /API/v1.0/REST/alias?getAlias={value}

Body Fields

Parameter Type Description Required Default
getAlias Bool Returns the created alias No false

Returns

Code Description
200 Successful request
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Get all aliases

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/alias' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/alias' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/alias", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/alias");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/alias');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/alias',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/alias")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/alias");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/alias";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "alias": [
        {
            "contact-surname": "Dallago",
            "notification-time": "20140704124747",
            "cod-fiscale": "01843020221",
            "alias-state": 3,
            "contact-city": "Trento",
            "id-alias": 36,
            "contact-pcode": "38122",
            "vat-number": "01843020221",
            "alias": "Alias123",
            "company-name": "smSend",
            "contact-type": "FAX",
            "contact-info": "024113727142",
            "contact-name": "Stefano",
            "is-numeric": false,
            "contact-address": "Via Rosaccio 6"
        },
        {
            "contact-surname": "Dallago",
            "notification-time": "20161123155102",
            "cod-fiscale": "01843020221",
            "alias-state": 2,
            "contact-city": "Trento",
            "id-alias": 662,
            "contact-pcode": "38122",
            "vat-number": "03843020821",
            "alias": "dunp",
            "company-name": "smSend",
            "contact-type": "FAX",
            "contact-info": "04317378142",
            "contact-name": "Stefano",
            "is-numeric": false,
            "contact-address": "Via Rosaccio 6"
        }
    ],
    "total": 2,
    "pageNumber": 1,
    "result": "OK",
    "pageSize": 10
}

Returns a paginated list of the user’s TPOA aliases.

HTTP Request

GET /API/v1.0/REST/alias?pageNumber={page}&pageSize={size}&hide-not-approved={value}

Parameters

Parameter Type Description Required Default
pageNumber Int Return the given results page No 1
pageSize Int The number of results in a page No 10
hide-not-approved Bool Show or hide not-yet-approved aliases No false

Returns

Code Description
200 The paginated list of the user’s TPOA aliases
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

The alias-state attribute in the returned objects represents the status of the TPOA confirmation process. It can be one of the following:

alias-state Description
0 Unconfirmed
1 Confirmed by smSend
2 Confirmed by AGCOM
3 Blocked by smSend
4 Blocked by AGCOM
9 The Alias has been pre-confirmed by smSend

Get a specific alias

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
   "result":"OK",
   "alias":{
      "id-alias":35,
      "alias":"+393458922223",
      "notification-time":"20140704141759",
      "alias-state":3,
      "is-numeric":true,
      "company-name":"aCompany",
      "contact-name":null,
      "contact-surname":null,
      "cod-fiscale":"",
      "vat-number":"",
      "contact-address":null,
      "contact-city":null,
      "contact-pcode":null,
      "contact-type":"123456789",
      "contact-info":""
   }
}

Returns the data of the given TPOA Alias ID.

HTTP Request

GET /API/v1.0/REST/alias/{alias_id}

Parameters

Parameter Type Description Required Default
alias_id Int The alias ID Yes -

Returns

Code Description
200 The requested TPOA Alias data
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The alias was not found

The alias-state attribute in the returned object represents the status of the TPOA confirmation process. It can be one of the following:

alias-state Description
0 Unconfirmed
1 Confirmed by smSend
2 Confirmed by AGCOM
3 Blocked by smSend
4 Blocked by AGCOM
9 The Alias has been pre-confirmed by smSend

Remove an alias

# Session Key example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.delete("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("DELETE");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}',
    method: 'DELETE',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                wb.UploadValues("http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}", "DELETE", new NameValueCollection());

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/alias/{alias_id}";

my $req = HTTP::Request->new(DELETE => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
  "result": "OK"
}

Deletes the given TPOA Alias.

HTTP Request

DELETE /API/v1.0/REST/alias/{alias_id}

Parameters

Parameter Type Description Required Default
alias_id Int The alias ID Yes -

Returns

Code Description
200 Alias successfully deleted
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The alias was not found

SMS Send API

This is the part of the API that allows to send SMS messages, to single recipients, saved contacts or groups of contacts.

Send an SMS message

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/sms' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "+393471234567", 
        "+393471234568"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/sms' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "+393471234567", 
        "+393471234568"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "+393471234567", 
        "+393471234568"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/sms", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/sms");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"returnCredits\": true, " + 
              "    \"order_id\": \"123456789\", " + 
              "    \"recipient\": [" + 
              "        \"+393471234567\", " + 
              "        \"+393471234568\"" + 
              "    ], " + 
              "    \"scheduled_delivery_time\": \"20161223101010\", " + 
              "    \"message\": \"Hello world!\", " + 
              "    \"message_type\": \"GP\", " + 
              "    \"sender\": \"MySender\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "returnCredits": true, ' . 
  '    "order_id": "123456789", ' . 
  '    "recipient": [' . 
  '        "+393471234567", ' . 
  '        "+393471234568"' . 
  '    ], ' . 
  '    "scheduled_delivery_time": "20161223101010", ' . 
  '    "message": "Hello world!", ' . 
  '    "message_type": "GP", ' . 
  '    "sender": "MySender"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/sms');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/sms',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "returnCredits": true, 
        "order_id": "123456789", 
        "recipient": [
            "+393471234567", 
            "+393471234568"
        ], 
        "scheduled_delivery_time": "20161223101010", 
        "message": "Hello world!", 
        "message_type": "GP", 
        "sender": "MySender"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/sms")
payload =     {
        "returnCredits": true, 
        "order_id": "123456789", 
        "recipient": [
            "+393471234567", 
            "+393471234568"
        ], 
        "scheduled_delivery_time": "20161223101010", 
        "message": "Hello world!", 
        "message_type": "GP", 
        "sender": "MySender"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"returnCredits\": true, " + 
                  "    \"order_id\": \"123456789\", " + 
                  "    \"recipient\": [" + 
                  "        \"+393471234567\", " + 
                  "        \"+393471234568\"" + 
                  "    ], " + 
                  "    \"scheduled_delivery_time\": \"20161223101010\", " + 
                  "    \"message\": \"Hello world!\", " + 
                  "    \"message_type\": \"GP\", " + 
                  "    \"sender\": \"MySender\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/sms", "POST", payload)

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/sms";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "returnCredits" => true, 
    "order_id" => "123456789", 
    "recipient" => [
        "+393471234567", 
        "+393471234568"
    ], 
    "scheduled_delivery_time" => "20161223101010", 
    "message" => "Hello world!", 
    "message_type" => "GP", 
    "sender" => "MySender"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result" : "OK",                    "//OK or errors"
    "order_id" : "123456789",
    "total_sent" : 2                    "//SMS sent or credits used"
}

Sends an SMS message to a given list of recipients.

HTTP Request

POST /API/v1.0/REST/sms

Body Fields

Parameter Type Description Required Default
message_type String (“N” for High quality with reception notification, “L” for Medium Quality, “LL” For Low Cost) The type of SMS. Yes -
message String (max 1000 chars*) The body of the message. *Message max length could be 160 chars when using low-quality SMSs Yes -
recipient List(String) A list of recipents phone numbers Yes -
sender String The Sender name. If the message type allows a custom TPOA and the field is left empty, the user’s preferred TPOA is used. Must be empty if the message type does not allow a custom TPOA No “”
scheduled_delivery_time String [ddMMyy, yyyyMMdd, ddMMyyHHmm, yyyyMMddHHmmss, yyyy-MM-dd HH:mm, yyyy-MM-dd HH:mm.0] The messages will be sent at the given scheduled time No null
order_id String Specifies a custom order ID No Generated UUID
returnCredits Bool Returns the number of credits used instead of the number of messages. i.e. when message is more than 160 chars long more than one credit is used No “false”
encoding String (“gsm” or “ucs2”) The SMS encoding. Use UCS2 for non standard character sets No “gsm”

Returns

Code Description
201 SMSs have been scheduled for delivery.
400 Invalid input. Details are in the response body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Send a parametric SMS message

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/paramsms' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "message_type": "GP", 
    "message": "Hello {name}, welcome to {nation}", 
    "sender": "MySender", 
    "scheduled_delivery_time": "20161223101010", 
    "order_id": "123456789", 
    "returnCredits": true, 
    "allowInvalidRecipients": false, 
    "returnRemaining": true, 
    "recipients": {
        "0": {
            "recipient": "+393471234567", 
            "name": "Mark"
        }, 
        "1": {
            "recipient": "+393477654321", 
            "nation": "Alabama"
        }
    }
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/paramsms' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "message_type": "GP", 
    "message": "Hello {name}, welcome to {nation}", 
    "sender": "MySender", 
    "scheduled_delivery_time": "20161223101010", 
    "order_id": "123456789", 
    "returnCredits": true, 
    "allowInvalidRecipients": false, 
    "returnRemaining": true, 
    "recipients": {
        "0": {
            "recipient": "+393471234567", 
            "name": "Mark"
        }, 
        "1": {
            "recipient": "+393477654321", 
            "nation": "Alabama"
        }
    }
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "message_type": "GP", 
    "message": "Hello {name}, welcome to {nation}", 
    "sender": "MySender", 
    "scheduled_delivery_time": "20161223101010", 
    "order_id": "123456789", 
    "returnCredits": true, 
    "allowInvalidRecipients": false, 
    "returnRemaining": true, 
    "recipients": {
        "0": {
            "recipient": "+393471234567", 
            "name": "Mark"
        }, 
        "1": {
            "recipient": "+393477654321", 
            "nation": "Alabama"
        }
    }
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/paramsms", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/paramsms");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"message_type\": \"GP\", " + 
              "    \"message\": \"Hello {name}, welcome to {nation}\", " + 
              "    \"sender\": \"MySender\", " + 
              "    \"scheduled_delivery_time\": \"20161223101010\", " + 
              "    \"order_id\": \"123456789\", " + 
              "    \"returnCredits\": true, " + 
              "    \"allowInvalidRecipients\": false, " + 
              "    \"returnRemaining\": true, " + 
              "    \"recipients\": {" + 
              "        \"0\": {" + 
              "            \"recipient\": \"+393471234567\", " + 
              "            \"name\": \"Mark\"" + 
              "        }, " + 
              "        \"1\": {" + 
              "            \"recipient\": \"+393477654321\", " + 
              "            \"nation\": \"Alabama\"" + 
              "        }" + 
              "    }" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "message_type": "GP", ' . 
  '    "message": "Hello {name}, welcome to {nation}", ' . 
  '    "sender": "MySender", ' . 
  '    "scheduled_delivery_time": "20161223101010", ' . 
  '    "order_id": "123456789", ' . 
  '    "returnCredits": true, ' . 
  '    "allowInvalidRecipients": false, ' . 
  '    "returnRemaining": true, ' . 
  '    "recipients": {' . 
  '        "0": {' . 
  '            "recipient": "+393471234567", ' . 
  '            "name": "Mark"' . 
  '        }, ' . 
  '        "1": {' . 
  '            "recipient": "+393477654321", ' . 
  '            "nation": "Alabama"' . 
  '        }' . 
  '    }' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/paramsms');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/paramsms',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "message_type": "GP", 
        "message": "Hello {name}, welcome to {nation}", 
        "sender": "MySender", 
        "scheduled_delivery_time": "20161223101010", 
        "order_id": "123456789", 
        "returnCredits": true, 
        "allowInvalidRecipients": false, 
        "returnRemaining": true, 
        "recipients": {
            "0": {
                "recipient": "+393471234567", 
                "name": "Mark"
            }, 
            "1": {
                "recipient": "+393477654321", 
                "nation": "Alabama"
            }
        }
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/paramsms")
payload =     {
        "message_type": "GP", 
        "message": "Hello {name}, welcome to {nation}", 
        "sender": "MySender", 
        "scheduled_delivery_time": "20161223101010", 
        "order_id": "123456789", 
        "returnCredits": true, 
        "allowInvalidRecipients": false, 
        "returnRemaining": true, 
        "recipients": {
            "0": {
                "recipient": "+393471234567", 
                "name": "Mark"
            }, 
            "1": {
                "recipient": "+393477654321", 
                "nation": "Alabama"
            }
        }
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"message_type\": \"GP\", " + 
                  "    \"message\": \"Hello {name}, welcome to {nation}\", " + 
                  "    \"sender\": \"MySender\", " + 
                  "    \"scheduled_delivery_time\": \"20161223101010\", " + 
                  "    \"order_id\": \"123456789\", " + 
                  "    \"returnCredits\": true, " + 
                  "    \"allowInvalidRecipients\": false, " + 
                  "    \"returnRemaining\": true, " + 
                  "    \"recipients\": {" + 
                  "        \"0\": {" + 
                  "            \"recipient\": \"+393471234567\", " + 
                  "            \"name\": \"Mark\"" + 
                  "        }, " + 
                  "        \"1\": {" + 
                  "            \"recipient\": \"+393477654321\", " + 
                  "            \"nation\": \"Alabama\"" + 
                  "        }" + 
                  "    }" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/paramsms", "POST", payload)

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/paramsms";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "message_type" => "GP", 
    "message" => "Hello {name}, welcome to {nation}", 
    "sender" => "MySender", 
    "scheduled_delivery_time" => "20161223101010", 
    "order_id" => "123456789", 
    "returnCredits" => true, 
    "allowInvalidRecipients" => false, 
    "returnRemaining" => true, 
    "recipients" => {
        "0" => {
            "recipient" => "+393471234567", 
            "name" => "Mark"
        }, 
        "1" => {
            "recipient" => "+393477654321", 
            "nation" => "Alabama"
        }
    }
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result" : "OK",                    "//OK or errors"
    "order_id" : "123456789",
    "total_sent" : 2                    "//SMS sent or credits used"
}

Sends a parametric SMS message to a given list of recipients. With this API it is possible to put placeholders in the message body, and then, for each recipient, specify the values that will replace the placeholders in the message body, for that particular recipient message.

HTTP Request

POST /API/v1.0/REST/paramsms

Body Fields

Parameter Type Description Required Default
message_type String (“N” for High quality with reception notification, “L” for Medium Quality, “LL” For Low Cost) The type of SMS. Yes -
message String (max 1000 chars*) The body of the message. *Message max length could be 160 chars when using low-quality SMSs Yes -
sender String The Sender name. If the message type allows a custom TPOA and the field is left empty, the user’s preferred TPOA is used. Must be empty if the message type does not allow a custom TPOA No “”
scheduled_delivery_time String [ddMMyy, yyyyMMdd, ddMMyyHHmm, yyyyMMddHHmmss, yyyy-MM-dd HH:mm, yyyy-MM-dd HH:mm.0] The messages will be sent at the given scheduled time No null
order_id String Specifies a custom order ID No Generated UUID
returnCredits Bool Returns the number of credits used instead of the number of messages. i.e. when message is more than 160 chars long more than one credit is used No false
returnRemaining Bool Returs the number of remaining SMSs No false
allowInvalidRecipients Bool Sending to an invalid recipient does not block the operation No false
recipients Map(String, Map(String, String)) A map of recipents and relative parameters Yes -
encoding String (“gsm” or “ucs2”) The SMS encoding. Use UCS2 for non standard character sets No “gsm”

Returns

Code Description
200 SMS have been successfully sent. The order ID and some other informations are returned
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Send an SMS message to a group

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/smstogroups' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "Group1", 
        "Group2"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/smstogroups' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "Group1", 
        "Group2"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "returnCredits": true, 
    "order_id": "123456789", 
    "recipient": [
        "Group1", 
        "Group2"
    ], 
    "scheduled_delivery_time": "20161223101010", 
    "message": "Hello world!", 
    "message_type": "GP", 
    "sender": "MySender"
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/smstogroups", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/smstogroups");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"returnCredits\": true, " + 
              "    \"order_id\": \"123456789\", " + 
              "    \"recipient\": [" + 
              "        \"Group1\", " + 
              "        \"Group2\"" + 
              "    ], " + 
              "    \"scheduled_delivery_time\": \"20161223101010\", " + 
              "    \"message\": \"Hello world!\", " + 
              "    \"message_type\": \"GP\", " + 
              "    \"sender\": \"MySender\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "returnCredits": true, ' . 
  '    "order_id": "123456789", ' . 
  '    "recipient": [' . 
  '        "Group1", ' . 
  '        "Group2"' . 
  '    ], ' . 
  '    "scheduled_delivery_time": "20161223101010", ' . 
  '    "message": "Hello world!", ' . 
  '    "message_type": "GP", ' . 
  '    "sender": "MySender"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/smstogroups');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/smstogroups',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "returnCredits": true, 
        "order_id": "123456789", 
        "recipient": [
            "Group1", 
            "Group2"
        ], 
        "scheduled_delivery_time": "20161223101010", 
        "message": "Hello world!", 
        "message_type": "GP", 
        "sender": "MySender"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/smstogroups")
payload =     {
        "returnCredits": true, 
        "order_id": "123456789", 
        "recipient": [
            "Group1", 
            "Group2"
        ], 
        "scheduled_delivery_time": "20161223101010", 
        "message": "Hello world!", 
        "message_type": "GP", 
        "sender": "MySender"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"returnCredits\": true, " + 
                  "    \"order_id\": \"123456789\", " + 
                  "    \"recipient\": [" + 
                  "        \"Group1\", " + 
                  "        \"Group2\"" + 
                  "    ], " + 
                  "    \"scheduled_delivery_time\": \"20161223101010\", " + 
                  "    \"message\": \"Hello world!\", " + 
                  "    \"message_type\": \"GP\", " + 
                  "    \"sender\": \"MySender\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/smstogroups", "POST", payload)

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/smstogroups";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "returnCredits" => true, 
    "order_id" => "123456789", 
    "recipient" => [
        "Group1", 
        "Group2"
    ], 
    "scheduled_delivery_time" => "20161223101010", 
    "message" => "Hello world!", 
    "message_type" => "GP", 
    "sender" => "MySender"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result" : "OK",                    "//OK or errors"
    "order_id" : "123456789",
    "total_sent" : 2                    "//SMS sent or credits used"
}

Send an SMS message to a set of contacts groups.

HTTP Request

POST /API/v1.0/REST/smstogroups

Returns

Code Description
200 Successful request
400 Groups could not be found, or other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Get SMS message state

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "recipient_number": 1,
    "result": "OK",
    "recipients": [
        {
            "status": "WAITING",
            "destination": "+393471234567",
            "delivery_date": ""
        }
    ]
}

Get informations on the SMS delivery status of the given order_id.

HTTP Request

GET /API/v1.0/REST/sms/{order_id}

Parameters

Parameter Type Description Required Default
order_id String The order ID Yes -

Returns

Code Description
200 A Json object representing the status of the given SMS order.
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The order_id was not found

Delete a scheduled message

# Session Key example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XDELETE 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.delete("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("DELETE");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}',
    method: 'DELETE',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                wb.UploadValues("http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}", "DELETE", new NameValueCollection());

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/sms/{order_id}";

my $req = HTTP::Request->new(DELETE => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{"result":"OK"}

Deletes the SMS delivery process of the given order_id.

HTTP Request

DELETE /API/v1.0/REST/sms/{order_id}

Parameters

Parameter Type Description Required Default
order_id String The order id Yes -

Returns

Code Description
200 Scheduled Message sending
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The given order_id was not found, or the message sending could not be removed (e.g. Message status is not “SCHEDULED”)

SMS History API

This API is used to retrieve the SMS messages sending history.

Get sent SMS messages history

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/smshistory?from={date}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "total": 1,                                  "// The total number of results"
    "pageNumber": 1,                             "// The returned page number"
    "result": "OK",                              "// The status of the request"
    "pageSize": 10,                              "// The page size"
    "smshistory": [                              "// The SMS history"
        {   
            "order_id" : "XYZABCQWERTY",         "// The order ID"  
            "create_time" : "yyyyMMddHHmmss",    "// When the order was created"        
            "schedule_time" : "yyyyMMddHHmmss",  "// When the sending is scheduled"
            "message_type" : "GP",               "// The message type"
            "sender" : "MySender",               "// The sender's alias"
            "num_recipients" : 2                 "// The number of recipients"
        },      
        {       
            ...     
        }
    ]
}

Returns the user’s SMS messages history

HTTP Request

GET /API/v1.0/REST/smshistory?from={fromdate}&to={todate}&pageNumber={page}&pageSize={size}

Parameters

Parameter Type Description Required Default
from Date(yyyyMMddHHmmss) Return results from the given date Yes -
to Date(yyyyMMddHHmmss) Return results up to the given date No now
pageNumber Int Return the given results page No 1
pageSize Int The number of results in a page No 10

Returns

Code Description
200 A paginated list of the SMS history filtered as specified by the from and to dates.
400 from parameter not specified, or an error in the from or to date format. Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Received SMS API

This API allows to query the received SMS messages on the owned SIMs.

Get new received messages

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/newsrsmsmessage";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result": "OK",
    "srsmshistory": [
        {
                  "id_message": "31",
                  "id_sim": "+393400000001",
                  "sender": "+393356242290",
                  "message": "sadasd",
                  "sms_date": "20160503102231",
                  "keyword": "qwe"
        },
        {
                  "id_message": "29",
                  "id_sim": "+393400000001",
                  "sender": "+393356242290",
                  "message": "sadasd",
                  "sms_date": "20160503102231",
                  "keyword": "qwe"
        }
    ]
}

Returns the list of received messages on the given sim_id since the last call of this method, or the beginning of time if it’s the first call. The list is limited to max. 100 entries.

HTTP Request

For all SIMs, use:

GET /API/v1.0/REST/newsrsmsmessage?limit={limit}

For one or more specific SIMs, use:

GET /API/v1.0/REST/newsrsmsmessage/{id_sim}?limit={limit}

Parameters

Parameter Type Description Required Default
id_sim String(PhoneNumber) The phone number where you enabled the service of reception, in international format (+393471234567 or 00393471234567). If no SIM is specified, returns the new messages for all enabled SIMs. It is possible to specify more numbers, separated by comma No All SIMs
limit Int (max 100) The max. number of entries returned No 100

Returns

Code Description
200 The list of received SMS messages since the last call of this method.
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Get the received SMS messages

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory?from={fromdate}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result": "OK",
    "srsmshistory": [
        {
              "id_message": "2",
              "id_sim": "+393400000001",
              "sender": "+393356242290",
              "message": "abcde",
              "sms_date": "20160503102231",
              "keyword": ""
            }
    ],
    "pageNumber": 1,
    "pageSize": 10,
    "total": 1
}

Get the paginated list of received SMS messages.

HTTP Request

For all SIMs, use:

GET /API/v1.0/REST/srsmshistory?from={fromdate}&to={todate}&pageNumber={page}&pageSize={size}

For one or more specific SIMs, use:

GET /API/v1.0/REST/srsmshistory/{id_sim}?from={fromdate}&to={todate}&pageNumber={page}&pageSize={size}

Parameters

Parameter Type Description Required Default
id_sim String(PhoneNumber) The phone number where you enabled the service of reception, in international format (+393471234567 or 00393471234567). If no SIM is specified, returns the new messages for all enabled SIMs. It is possible to specify more numbers, separated by comma No All SIMs
from Date(yyyyMMddHHmmss) Return results from the given date Yes -
to Date(yyyyMMddHHmmss) Return results up to the given date No now
pageNumber Int Return the given results page No 1
pageSize Int The number of results in a page No 10

Returns

Code Description
200 The paginated list of received SMS messages.
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Get the received SMS messages after a specified message.

# Session Key example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XGET 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.get("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    response = r.text

    obj = json.loads(response)
    print(unicode(obj))

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("GET");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            BufferedReader br =
                new BufferedReader(new InputStreamReader(conn.getInputStream()));

            String response = "";
            String output;
            while ((output = br.readLine()) != null) {
                response += output;
            }
            // You can parse the response using Google GSON or similar.
            // MyObject should be a class that reflect the JSON 
            // structure of the response

            GsonBuilder builder = new GsonBuilder();
            Gson gson = builder.create();
            MyObject responseObj = gson.fromJson(response, MyObject.class);
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);


$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {

    $obj = json_decode($response);
    print_r($obj);
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}',
    method: 'GET',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {

        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body

  obj = JSON.parse(response)
  puts obj
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.DownloadString("http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}");

                dynamic obj = JsonConvert.DeserializeObject(response);
                Console.WriteLine(obj);
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/srsmshistory/{id_sim}/{id_message}";

my $req = HTTP::Request->new(GET => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  my $obj = from_json($response);

}

On success, the above command returns the following response:

{
    "result": "OK",
    "srsmshistory": [
        {
              "id_message": "6",
              "id_sim": "+393400000000",
              "sender": "+393356242290",
              "message": "abcdef",
              "sms_date": "20160503102231",
              "keyword": ""
        },
        {
              "id_message": "7",
              "id_sim": "+393400000000",
              "sender": "+393356242290",
              "message": "abcdef",
              "sms_date": "20160503102231",
              "keyword": ""
        },
        {
              "id_message": "8",
              "id_sim": "+393400000000",
              "sender": "+393356242290",
              "message": "abcdef",
              "sms_date": "20160503102231",
              "keyword": ""
        }
      ]
}

Returns a list (limited to max. 100 entries) of SMS messages received after the given SMS message ID id_message, for the given SIM id_sim.

HTTP Request

GET /API/v1.0/REST/srsmshistory/{id_sim}/{id_message}?limit={limit}

Parameters

Parameter Type Description Required Default
id_sim String (Phone number) The phone number where you enabled the service of reception, in international format (+393471234567 or 00393471234567) Yes -
id_message Int The reference message ID Yes -
limit Int (max. 100) The max. number of entries in the returned list No 100

Returns

Code Description
200 The list of received SMS messages after the given message.
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Email Campaign API

This API exposes methods for creating and managing Email campaigns.

Emails can be sent to a list, that is used for contacts subscription. A list allows contacts to subscribe to it, and also defines some basic email sending settings, such as: - Name of the list - Language - Sender’s name and email - Reply-to email - Customized Opt-in email

An Email campaign is a sending of an email to a certain list.

Create a new list

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/list", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/list");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"title\": \"MyNewList\", " + 
              "    \"id_language\": \"ita\", " + 
              "    \"email_sender\": \"ema@il.com\", " + 
              "    \"reply_to\": \"ema@il.com\", " + 
              "    \"company_name\": \"MyCompany\", " + 
              "    \"company_address\": \"My Company Address\", " + 
              "    \"company_url\": \"www.mycompany.com\", " + 
              "    \"company_phone\": \"+34123456789\", " + 
              "    \"company_fax\": \"+341234567810\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "title": "MyNewList", ' . 
  '    "id_language": "ita", ' . 
  '    "email_sender": "ema@il.com", ' . 
  '    "reply_to": "ema@il.com", ' . 
  '    "company_name": "MyCompany", ' . 
  '    "company_address": "My Company Address", ' . 
  '    "company_url": "www.mycompany.com", ' . 
  '    "company_phone": "+34123456789", ' . 
  '    "company_fax": "+341234567810"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/list');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/list',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "title": "MyNewList", 
        "id_language": "ita", 
        "email_sender": "ema@il.com", 
        "reply_to": "ema@il.com", 
        "company_name": "MyCompany", 
        "company_address": "My Company Address", 
        "company_url": "www.mycompany.com", 
        "company_phone": "+34123456789", 
        "company_fax": "+341234567810"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/list")
payload =     {
        "title": "MyNewList", 
        "id_language": "ita", 
        "email_sender": "ema@il.com", 
        "reply_to": "ema@il.com", 
        "company_name": "MyCompany", 
        "company_address": "My Company Address", 
        "company_url": "www.mycompany.com", 
        "company_phone": "+34123456789", 
        "company_fax": "+341234567810"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"title\": \"MyNewList\", " + 
                  "    \"id_language\": \"ita\", " + 
                  "    \"email_sender\": \"ema@il.com\", " + 
                  "    \"reply_to\": \"ema@il.com\", " + 
                  "    \"company_name\": \"MyCompany\", " + 
                  "    \"company_address\": \"My Company Address\", " + 
                  "    \"company_url\": \"www.mycompany.com\", " + 
                  "    \"company_phone\": \"+34123456789\", " + 
                  "    \"company_fax\": \"+341234567810\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/list", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/list";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "title" => "MyNewList", 
    "id_language" => "ita", 
    "email_sender" => "ema@il.com", 
    "reply_to" => "ema@il.com", 
    "company_name" => "MyCompany", 
    "company_address" => "My Company Address", 
    "company_url" => "www.mycompany.com", 
    "company_phone" => "+34123456789", 
    "company_fax" => "+341234567810"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 201) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Create a new sending list.

HTTP Request

POST /API/v1.0/REST/list

Body Fields

Parameter Type Description Required Default
title String The list name Yes -
id_language String (e.g. “ita”) The list default language Yes -
email_sender a valid email The sender’s email address Yes -
reply_to a valid email The email to be used for the ‘reply_to’ email field Yes -
company_name String The company name Yes -
company_address String The company address Yes -
company_url String The company website URL Yes -
company_phone String The company phone number Yes -
company_fax String The company FAX number Yes -

Returns

Code Description
201 List created, The HTTP location header that points to the created list
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Modify a list

# Session Key example
curl -XPUT 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}
'

# Access token example
curl -XPUT 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "title": "MyNewList", 
    "id_language": "ita", 
    "email_sender": "ema@il.com", 
    "reply_to": "ema@il.com", 
    "company_name": "MyCompany", 
    "company_address": "My Company Address", 
    "company_url": "www.mycompany.com", 
    "company_phone": "+34123456789", 
    "company_fax": "+341234567810"
}"""

r = requests.put("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}", headers=headers, data=payload)

if r.status_code != 204:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("PUT");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"title\": \"MyNewList\", " + 
              "    \"id_language\": \"ita\", " + 
              "    \"email_sender\": \"ema@il.com\", " + 
              "    \"reply_to\": \"ema@il.com\", " + 
              "    \"company_name\": \"MyCompany\", " + 
              "    \"company_address\": \"My Company Address\", " + 
              "    \"company_url\": \"www.mycompany.com\", " + 
              "    \"company_phone\": \"+34123456789\", " + 
              "    \"company_fax\": \"+341234567810\"" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 204) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "title": "MyNewList", ' . 
  '    "id_language": "ita", ' . 
  '    "email_sender": "ema@il.com", ' . 
  '    "reply_to": "ema@il.com", ' . 
  '    "company_name": "MyCompany", ' . 
  '    "company_address": "My Company Address", ' . 
  '    "company_url": "www.mycompany.com", ' . 
  '    "company_phone": "+34123456789", ' . 
  '    "company_fax": "+341234567810"' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_PUT, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 204) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}',
    method: 'PUT',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "title": "MyNewList", 
        "id_language": "ita", 
        "email_sender": "ema@il.com", 
        "reply_to": "ema@il.com", 
        "company_name": "MyCompany", 
        "company_address": "My Company Address", 
        "company_url": "www.mycompany.com", 
        "company_phone": "+34123456789", 
        "company_fax": "+341234567810"
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 204) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}")
payload =     {
        "title": "MyNewList", 
        "id_language": "ita", 
        "email_sender": "ema@il.com", 
        "reply_to": "ema@il.com", 
        "company_name": "MyCompany", 
        "company_address": "My Company Address", 
        "company_url": "www.mycompany.com", 
        "company_phone": "+34123456789", 
        "company_fax": "+341234567810"
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Put.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "204"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"title\": \"MyNewList\", " + 
                  "    \"id_language\": \"ita\", " + 
                  "    \"email_sender\": \"ema@il.com\", " + 
                  "    \"reply_to\": \"ema@il.com\", " + 
                  "    \"company_name\": \"MyCompany\", " + 
                  "    \"company_address\": \"My Company Address\", " + 
                  "    \"company_url\": \"www.mycompany.com\", " + 
                  "    \"company_phone\": \"+34123456789\", " + 
                  "    \"company_fax\": \"+341234567810\"" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}", "PUT", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}";

my $req = HTTP::Request->new(PUT => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "title" => "MyNewList", 
    "id_language" => "ita", 
    "email_sender" => "ema@il.com", 
    "reply_to" => "ema@il.com", 
    "company_name" => "MyCompany", 
    "company_address" => "My Company Address", 
    "company_url" => "www.mycompany.com", 
    "company_phone" => "+34123456789", 
    "company_fax" => "+341234567810"
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 204) {
  $response = $resp->decoded_content;
  print "Success!";

}

On success, the above command returns the following response:

# The HTTP location header that points to the updated list:
'Location': '/list/{list_id}'

Updates a sending list.

HTTP Request

PUT /API/v1.0/REST/list/{list_id}

Parameters

Parameter Type Description Required Default
list_id Int The ID of the list to modify Yes -

Body Fields

Parameter Type Description Required Default
title String The list name No -
id_language String (e.g. “ita”) The list default language No -
email_sender a valid email The sender’s email address No -
reply_to a valid email The email to be used for the ‘reply_to’ email field No -
company_name String The company name No -
company_address String The company address No -
company_url String The company website URL No -
company_phone String The company phone number No -
company_fax String The company FAX number No -
status Int The list status (0 = Active, 1 = Archived, 2 = To Be Activated) No -

Returns

Code Description
204 List updated, The HTTP location header that points to the created list
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Add a contacts group to a list of distribution

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' 

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' 
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}", headers=headers)

if r.status_code != 200:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 200) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 200) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}")

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'

# Send the request
responseData = http.request(request)
if responseData.code == "200"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}", "POST", null)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/group/{group_id}";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $resp = $ua->request($req);
if ($resp->is_success && $resp->code == 200) {
  $response = $resp->decoded_content;
  print "Success!";

}

Add all contacts of the given group to the given list of distribution. Emails can be only sent to contacts that belong to a distribution list.

HTTP Request

POST /API/v1.0/REST/list/{list_id}/group/{group_id}?sendoptin={send}

Parameters

Parameter Type Description Required Default
list_id Int The list ID Yes -
group_id String The group ID Yes -
sendoptin Bool Send the Opt-in email to the group’s contacts No false

Returns

Code Description
200 The group has been added to the list
400 Other errors, details are in the body
401 [Unauthorized] User_key, Token or Session_key are invalid or not provided
404 [Not found] The User_key was not found

Create a new email draft

# Session Key example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue' -H 'Content-Type: application/json' \
-H 'user_key: {USER_KEY}' -H 'Session_key: {SESSION_KEY}' -d'
{
    "title": "New title", 
    "subject": "Hello world!", 
    "share_social": false, 
    "web_analytics": "www.google.it?a=b", 
    "text_content": "Test email", 
    "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", 
    "attachments": [
        {
            "file_name": "attach1.pdf", 
            "file_content_base64": "ABAAC2"
        }, 
        {
            "file_name": "attach2.pdf", 
            "file_content_base64": "PBAAC2"
        }
    ]
}
'

# Access token example
curl -XPOST 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue' -H 'Content-Type: application/json' \
 -H 'user_key: {USER_KEY}' -H 'Access_token: {ACCESS_TOKEN}' -d'
{
    "title": "New title", 
    "subject": "Hello world!", 
    "share_social": false, 
    "web_analytics": "www.google.it?a=b", 
    "text_content": "Test email", 
    "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", 
    "attachments": [
        {
            "file_name": "attach1.pdf", 
            "file_content_base64": "ABAAC2"
        }, 
        {
            "file_name": "attach2.pdf", 
            "file_content_base64": "PBAAC2"
        }
    ]
}
'
# pip install requests
import requests
import json
# Use this when using Session Key authentication
headers = { 'user_key': '{USER_KEY}', 'Session_key' : '{SESSION_KEY}', 'Content-type' : 'application/json' }
# When using Access Token authentication, use this instead:
# headers = { 'user_key': '{USER_KEY}', 'Access_token' : '{ACCESS_TOKEN}', 'Content-type' : 'application/json' }
payload = """{
    "title": "New title", 
    "subject": "Hello world!", 
    "share_social": false, 
    "web_analytics": "www.google.it?a=b", 
    "text_content": "Test email", 
    "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", 
    "attachments": [
        {
            "file_name": "attach1.pdf", 
            "file_content_base64": "ABAAC2"
        }, 
        {
            "file_name": "attach2.pdf", 
            "file_content_base64": "PBAAC2"
        }
    ]
}"""

r = requests.post("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue", headers=headers, data=payload)

if r.status_code != 201:
    print("An error occurred, return code is: " + str(r.status_code))
else:
    print('Success!')

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        try {
            URL url = new URL("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestProperty("user_key", "{USER_KEY}");

            // Use this when using Session Key authentication
            conn.setRequestProperty("Session_key", "{SESSION_KEY}");                  
            // When using Access Token authentication, use this instead:
            // conn.setRequestProperty("Access_token", "{ACCESS_TOKEN}");

            conn.setRequestMethod("POST");

            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-type", "application/json");
            conn.setDoOutput(true);

            String payload = "{" + 
              "    \"title\": \"New title\", " + 
              "    \"subject\": \"Hello world!\", " + 
              "    \"share_social\": false, " + 
              "    \"web_analytics\": \"www.google.it?a=b\", " + 
              "    \"text_content\": \"Test email\", " + 
              "    \"html_content\": \"<body><table><tr><td>Hello world!</td></tr><table></body>\", " + 
              "    \"attachments\": [" + 
              "        {" + 
              "            \"file_name\": \"attach1.pdf\", " + 
              "            \"file_content_base64\": \"ABAAC2\"" + 
              "        }, " + 
              "        {" + 
              "            \"file_name\": \"attach2.pdf\", " + 
              "            \"file_content_base64\": \"PBAAC2\"" + 
              "        }" + 
              "    ]" + 
              "}";

            OutputStream os = conn.getOutputStream();
            os.write(payload.getBytes());
            os.flush();

            if (conn.getResponseCode() != 201) {
                throw new RuntimeException("Failed : HTTP error code : "
                                           + conn.getResponseCode());
            }
            System.out.println("Success!");
            conn.disconnect();
        }
        catch (Exception e) {
            e.printStackTrace();
        }
    }
}
<?php

$payload = '{' . 
  '    "title": "New title", ' . 
  '    "subject": "Hello world!", ' . 
  '    "share_social": false, ' . 
  '    "web_analytics": "www.google.it?a=b", ' . 
  '    "text_content": "Test email", ' . 
  '    "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", ' . 
  '    "attachments": [' . 
  '        {' . 
  '            "file_name": "attach1.pdf", ' . 
  '            "file_content_base64": "ABAAC2"' . 
  '        }, ' . 
  '        {' . 
  '            "file_name": "attach2.pdf", ' . 
  '            "file_content_base64": "PBAAC2"' . 
  '        }' . 
  '    ]' . 
  '}';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue');
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-type: application/json',
    'user_key: {USER_KEY}',
    // Use this when using session key authentication
    'Session_key: {SESSION_KEY}',
    // When using Access Token authentication, use this instead:
    // 'Access_token: {ACCESS_TOKEN}'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
$info = curl_getinfo($ch);
curl_close($ch);

if ($info['http_code'] != 201) {
    echo('Error!');
}
else {
    echo('Success!');
}
?>
// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue',
    method: 'POST',
    headers: { 'user_key' : '{USER_KEY}', 'Session_key' : '{SESSION_KEY}' },

    json: true,
    body:     {
        "title": "New title", 
        "subject": "Hello world!", 
        "share_social": false, 
        "web_analytics": "www.google.it?a=b", 
        "text_content": "Test email", 
        "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", 
        "attachments": [
            {
                "file_name": "attach1.pdf", 
                "file_content_base64": "ABAAC2"
            }, 
            {
                "file_name": "attach2.pdf", 
                "file_content_base64": "PBAAC2"
            }
        ]
    },

    callback: function (error, responseMeta, response) {
        if (!error && responseMeta.statusCode == 201) {
            console.log('Success!');
        }
        else {
            console.log('An error occurred..');
        }
    }
});
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue")
payload =     {
        "title": "New title", 
        "subject": "Hello world!", 
        "share_social": false, 
        "web_analytics": "www.google.it?a=b", 
        "text_content": "Test email", 
        "html_content": "<body><table><tr><td>Hello world!</td></tr><table></body>", 
        "attachments": [
            {
                "file_name": "attach1.pdf", 
                "file_content_base64": "ABAAC2"
            }, 
            {
                "file_name": "attach2.pdf", 
                "file_content_base64": "PBAAC2"
            }
        ]
    }

# Create the HTTP objects
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri)
request['Content-type'] = 'application/json'
request['user_key'] = '{USER_KEY}'
request['Session_key'] = '{SESSION_KEY}'
request.body = payload.to_json

# Send the request
responseData = http.request(request)
if responseData.code == "201"
  response = responseData.body
  puts "Success!"
else
  puts "Error.."
end                     
using System;
using System.Text;
using System.Net;
using System.Collections.Specialized;

// We are using JSON.NET (http://www.newtonsoft.com/json)
using Newtonsoft.Json;

/*
 * The following code has been compiled and tested using the MONO
 * project.
 * 
 * To compile using MONO:
 * mcs -r:Newtonsoft.Json.dll example.cs
 */
namespace RestApplication
{
    class Program
    {        
        static void Main(string[] args)
        {
            using (var wb = new WebClient())
            {
                wb.Headers.Set(HttpRequestHeader.ContentType, "application/json");
                wb.Headers.Add("user_key", "{USER_KEY}");
                wb.Headers.Add("Session_key", "{SESSION_KEY}");

                String payload = "{" + 
                  "    \"title\": \"New title\", " + 
                  "    \"subject\": \"Hello world!\", " + 
                  "    \"share_social\": false, " + 
                  "    \"web_analytics\": \"www.google.it?a=b\", " + 
                  "    \"text_content\": \"Test email\", " + 
                  "    \"html_content\": \"<body><table><tr><td>Hello world!</td></tr><table></body>\", " + 
                  "    \"attachments\": [" + 
                  "        {" + 
                  "            \"file_name\": \"attach1.pdf\", " + 
                  "            \"file_content_base64\": \"ABAAC2\"" + 
                  "        }, " + 
                  "        {" + 
                  "            \"file_name\": \"attach2.pdf\", " + 
                  "            \"file_content_base64\": \"PBAAC2\"" + 
                  "        }" + 
                  "    ]" + 
                  "}";

                String response = wb.UploadString("http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}
#!/usr/bin/env perl

use warnings;
use strict;
use LWP::UserAgent;

# Install using Cpan: "cpan JSON"
use JSON;

my $ua = LWP::UserAgent->new;

my $server_endpoint = "http://app.gateway.smsend.it/API/v1.0/REST/list/{list_id}/issue";

my $req = HTTP::Request->new(POST => $server_endpoint);

$req->header('Content_type' => 'application/json');

# IMPORTANT: Not adding the ':' before 'user_key' and
# 'Session_key' will result in perl to automatically rewrite the
# headers as 'User-Key' and 'Session-Key', which is not supported
# by our API.
$req->header(':user_key' => $auth->[0],
             ':Session_key' => $auth->[1]);
my $payload = {
    "title" => "New title", 
    "subject" => "Hello world!", 
    "share_social" => false, 
    "web_analytics" => "www.google.it?a=b", 
    "text_content" => "Test email", 
    "html_content" => "<body><table><tr><td>Hello world!</td></tr><table></body>", 
    "attachments" => [
        {
            "file_name" => "attach1.pdf", 
            "file_content_base64" => "ABAAC2"
        }, 
        {
            "file_name" => "attach2.pdf", 
            "file_content_base64" => "PBAAC2"
        }
    ]
};

$req->content(to_json($payload));
my $resp = $ua->request($req);
if ($resp->