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. Our examples are displayed by using CURL but you may find it easier using a service similar to

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.
Using GET parameter
$ curl{API_KEY}
Using HTTP basic auth
$ curl -u {API_KEY}:
define("API_KEY","YOUR API KEY");
$result = file_get_contents("".API_KEY);
$response = json_decode($result,true);

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
$ curl{API_KEY}
define("API_KEY","YOUR API KEY");
$result = file_get_contents("".API_KEY);
$response = json_decode($result,true);
      "created":"2014-06-26 00:00:00",
      "updated":"2014-06-26 00:00:00",
      "company":"Company Ltd",
      "address1":"14 Example House",
      "address2":"Example Street",
      "postcode":"EX01 1AB",
      "phone":"01234 567890"

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.

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
lasttname 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.

$ curl{API_KEY} \
-d "group_id=1" \
-d "on_duplicate=update" \
-d "firstname=Steve" \
-d "lastname=Parish" \
-d "address1=Unit 1 Willow Tree Court" \
-d "address2=Roundswell Business Park" \
-d "city=Barnstaple" \
-d "postcode=EX39 3TD" \
-d "country=GB"
define("API_KEY","YOUR API KEY");
$postdata = http_build_query(
  	'group_id' => "1",
  	'on_duplicate' => "update" ,
  	'firstname' => "Steve",
  	'lastname' => "Parish",
  	'address1' => "Unit 1 Willow Tree Court",
  	'address2' => "Roundswell Business Park",
  	'city' => "Barnstaple",
  	'postcode' => "EX39 3TD",
  	'country' => "GB"
$opts = array('http' => array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
$context  = stream_context_create($opts);
$result = file_get_contents("".API_KEY, false, $context);
$response = json_decode($result,true);