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.

Remember to provide the authentication HTTP headers as described in the Authenticate using a session key and the Authenticate using a user tokeny sections.

All the query string parameters in URL must be UTF-8 URL Encoded.

Create a new list

Create a new sending list.

HTTP Headers

user_key / Session_key

HTTP Method

POST

HTTP Request

https://app.gateway.smsend.it/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

Copy code

# Session Key example
curl -XPOST 'https://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 'https://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"
}
'

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

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("https://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();
        }
    }
}

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

<?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, 'https://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!');
}
?>

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

# 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("https://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!')

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

// Uses https://github.com/request/request
// npm install [-g] request

var request = require('request');

request({
    url: 'https://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..');
        }
    }
});

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

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

uri = URI.parse("https://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

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

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("https://app.gateway.smsend.it/API/v1.0/REST/list", "POST", payload)
                Console.WriteLine("Success!");
            }

        }
    }
}

On success, the above command returns the following response:
# The HTTP location header that points to the created list:
'Location': '/list/{list_id}'

Copy code

#!/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 = "https://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}'

Modify a list

Updates a sending list.

HTTP Headers

user_key / Session_key

HTTP Method

PUT

HTTP Request

https://app.gateway.smsend.it/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	-