Direct Mail API

An introduction to our API

Our APIs provide programmatic access to your Stannp Bulk Mailer account. Things like configuring campaigns, feeding data and triggering mail pieces to be dispatched can all be achieved using simple yet secure HTTP requests.

Example code
Throughout this documentation boxes like this will display relevant example code. We recommend using "postman" for an easy way to test our API's. You can download postman here: Get Postman

Authentication & security

Every API call to our service requires authenticating. This is simply done by passing your unique API key along with each request. We allow two methods of passing your API key, either send it as a GET parameter named "api_key" or by using the HTTP basic auth username parameter.

All API requests must be made over HTTPS so they are encrypted. Any requests made over HTTP will fail and could suspend your API key. Remember your API key is essentially your password, never share this with anybody that you don't want to access your account.

You can find your api key at the bottom of your settings page.

Authentication Example

$ curl https://api-us1.stannp.com/v1/users/me \
-u {API_KEY}:

define("API_KEY", "YOUR API KEY");
$opts = array(
    'http' => array(
        'method'  => 'GET',
        'header'  => 'Content-type: application/x-www-form-urlencoded'
    )
);
$context  = stream_context_create($opts);
$result = file_get_contents("https://api-us1.stannp.com/v1/users/me?api_key=" . API_KEY, false, $context);
$response = json_decode($result, true);

print_r($response);

import requests

response = requests.get('https://api-us1.stannp.com/v1/users/me?api_key={API_KEY}')
print(response.text)

var client = new RestClient("https://api-us1.stannp.com/v1/users/me?api_key={API_KEY}");

var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Console.WriteLine(response.Content);

Response

{
   "success":true,
   "data":{
      "account_id":"1",
      "email":"email@example.com",
      "created":"2014-06-26 00:00:00",
      "updated":"2014-06-26 00:00:00",
      "user_id":"1",
      "company":"Company Ltd",
      "job_title":"",
      "first_name":"John",
      "last_name":"Smith",
      "title":"Mr",
      "address1":"14 Example House",
      "address2":"Example Street",
      "address3":"",
      "city":"Exampltown",
      "county":"Exampleshire",
      "postcode":"EX01 1AB",
      "country":"GB",
      "phone":"01234 567890"
   }
}

API responses

All API requests return a JSON response and adhere to HTTP response codes. For example...

200 OK	This is a successful result.
401 Forbidden	You will most likely see this if you pass your API key incorrectly.
404 Not Found	If the resource does not exist or has been recently deleted.
500 Internal Server Error	Something went wrong at our end. Possibly experiencing server issues

Feeding recipient data

The most common reason for using our API is to automatically feed recipient data in to the system. For instance when a new customer signs up on a website their data could then be automatically fed into the Stannp platform. A mail campaign could then be set up to trigger posting the mail piece to that user welcoming them to the service.

For this example we will demonstrate how to feed data into a recipient group. If you haven't done so already, create a new group and take a note of the new group ID, you can see the ID on the left column when viewing your mailing groups page.

Now use the following example request to add a new recipient to a group.

[POST] https://api-us1.stannp.com/v1/recipients/new

group_id	int	The group ID you wish to add the data to.
on_duplicate	string	What to do if a duplicate is found (update/ignore/duplicate)
firstname	string	Recipients first name
lastname	string	Recipients last name
address1	string	Address line 1
address2	string	Address line 2
city	string	Address city
postcode	string	Address postal code
country	string	ISO 3166-1 Alpha 2 Country Code (GB,US,FR...)
?	?	If you have added custom fields to your recipients you can also add them as parameters when added new recipient records

The API will return a response to say if the request was successful or not. If successful the new recipients ID will be returned along with whether the address can be validated or not.

Now if you view your mailing list you can filter by group and see your newly inserted recipient.

Request

$ curl https://api-us1.stannp.com/v1/recipients/new \
-u {API_KEY}: \
-d "group_id=1" \ 
-d "on_duplicate=update" \ 
-d "firstname=Steve" \ 
-d "lastname=Parish" \ 
-d "address1=Unit 12 Taw Trade Park" \ 
-d "address2=Braunton Road" \ 
-d "city=Barnstaple" \ 
-d "postcode=EX31 1JZ" \ 
-d "country=GB" \ 
-d "voucher=GT4523"

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api-us1.stannp.com/v1/recipients/new?api_key={API_KEY}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array(
        'group_id' => "1",
        'on_duplicate' => "update",
        'firstname' => "Steve",
        'lastname' => "Parish",
        'address1' => "Unit 12 Taw Trade Park",
        'address2' => "Braunton Road",
        'city' => "Barnstaple",
        'postcode' => "EX31 1JZ",
        'country' => "GB",
        'voucher' => "GT4523"
    ),
));

$response = curl_exec($curl);

curl_close($curl);
print_r($response);

import requests

data = {
    'group_id': '1',
    'on_duplicate': 'update',
    'firstname': 'Steve',
    'lastname': 'Parish',
    'address1': 'Unit 12 Taw Trade Park',
    'address2': 'Braunton Road',
    'city': 'Barnstaple',
    'postcode': 'EX31 1JZ',
    'country': 'GB',
    'voucher': 'GT4523'
}

response = requests.post('https://api-us1.stannp.com/v1/recipients/new?api_key={API_KEY}', data=data)
print(response.text)

var client = new RestClient("https://api-us1.stannp.com/v1/recipients/new?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("group_id", "1");
request.AddParameter("on_duplicate", "update");
request.AddParameter("firstname", "Steve");
request.AddParameter("lastname", "Parish");
request.AddParameter("address1", "Unit 12 Taw Trade Park");
request.AddParameter("address2", "Braunton Road");
request.AddParameter("city", "Barnstaple");
request.AddParameter("postcode", "EX31 1JZ");
request.AddParameter("country", "GB");
request.AddParameter("voucher", "GT4523");

IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content)

Return

{
   "success":true,
   "data":{
      "id":"1941",
      "valid":true
   }
}