Direct Mail API - Guide

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.

[GET]
https://ca.stannp.com/api/v1/user/info
You can find your API key at the bottom of your settings page.

Request Example

        curl "https://ca.stannp.com/api/v1/user/info" \
-u {API_KEY}:

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 Codes

Status CodeDescription
200 OKThis is a successful result.
401 UnauthorizedInvalid API key or no API key provided.
404 Not FoundResource does not exist or was deleted.
500 Internal Server ErrorSomething 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.

[POST]
https://ca.stannp.com/api/v1/recipients/new
First, create a new group and note the group ID. Use this in the following request to add a recipient to the group:

Parameters

ParameterTypeDescription
group_idintThe group ID to add the recipient to.
on_duplicatestringAction to take if a duplicate is found (update/ignore/duplicate).
firstnamestringRecipient's first name.
lastnamestringRecipient's last name.
address1stringRecipient's address line 1.
citystringRecipient's city.
postcodestringRecipient's postal code.
countrystringISO 3166-1 Alpha 2 Country Code (GB,US,FR...).

Request Example

        curl "https://ca.stannp.com/api/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 "city=Barnstaple" \
-d "postcode=EX31 1JZ" \
-d "country=GB"

Response Example

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