API Documentation | Stannp

An introduction to our API

Our APIs provide programmatic access to your Stannp Bulk Mailer account. You can configure campaigns, feed data, and trigger mail pieces to be dispatched using simple and 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 APIs.

Authentication & security

Every API call to our service requires authentication. You can authenticate by passing your unique API key with each request, either as a GET parameter (`api_key`) or using HTTP basic auth. All API requests must be made over HTTPS for encryption. Requests made over HTTP will fail and could suspend your API key.

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

Authentication Example

                using RestSharp;

var client = new RestClient("https://api-us1.stannp.com/v1/user/info?api_key={API_KEY}");
var request = new RestRequest(Method.GET);

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

Response Example

{
    "success": true,
    "data": {
        "account_id": "1",
        "email": "email@example.com",
        "user_id": "1",
        "first_name": "John",
        "last_name": "Smith"
    }
}

API responses

All API requests return a JSON response with HTTP status codes. For example:

Status Code	Description
200 OK	This is a successful result.
401 Unauthorized	Invalid API key or no API key provided.
404 Not Found	Resource does not exist or was deleted.
500 Internal Server Error	Something went wrong at our end.

Feeding recipient data

The most common API use case is feeding recipient data into the system. For example, you can automatically feed new customer data into the Stannp platform for mailing campaigns.

First, create a new group and note the group ID. Use this in the following request to add a recipient to the group:

Parameters

group_id	int	The group ID to add the recipient to.
on_duplicate	string	Action to take if a duplicate is found (update/ignore/duplicate).
firstname	string	Recipient's first name.
lastname	string	Recipient's last name.
address1	string	Recipient's address line 1.
city	string	Recipient's city.
postcode	string	Recipient's postal code.
country	string	ISO 3166-1 Alpha 2 Country Code (GB,US,FR...).

View your mailing list to verify the recipient was added.

Request Example

                using RestSharp;

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("city", "Barnstaple");
request.AddParameter("postcode", "EX31 1JZ");
request.AddParameter("country", "GB");


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

Response Example

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