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.
Request Example
curl "https://api-eu1.stannp.com/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 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.
View your mailing list to verify the recipient was added.
Parameters
| Parameter | Details | Description |
|---|---|---|
| group_id | body int required | The group ID to add the recipient to. |
| on_duplicate | body str optional | Action to take if a duplicate is found (update/ignore/duplicate). |
| firstname | body str optional | Recipient's first name. |
| lastname | body str optional | Recipient's last name. |
| address1 | body str required | Recipient's address line 1. |
| city | body str required | Recipient's city. |
| postcode | body str required | Recipient's postal code. |
| country | body str required | ISO 3166-1 Alpha 2 Country Code (GB,US,FR...). |
Request Example
curl "https://api-eu1.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 "city=Barnstaple" \
-d "postcode=EX31 1JZ" \
-d "country=GB"
Response Example
{
"success": true,
"data": {
"id": "1941",
"valid": true
}
}