X

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

                import requests

response = requests.get("https://api-eu1.stannp.com/v1/user/info?api_key={API_KEY}")
print(response.text)

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

                import requests

data = {
    "group_id": "1",\n    "on_duplicate": "update",\n    "firstname": "Steve",\n    "lastname": "Parish",\n    "address1": "Unit 12 Taw Trade Park",\n    "city": "Barnstaple",\n    "postcode": "EX31 1JZ",\n    "country": "GB",\n
}

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

Response Example

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