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. To access the API you will need to be on a minimum of our starter subscription plan. View our pricing plans.
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/users/me" \
-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 | The request was successful. |
| 201 Created | The request was successful and a resource was created. |
| 204 No Content | The request was successful but there is no content to return. |
| 400 Bad Request | The request was malformed or missing required parameters. |
| 401 Unauthorized | Invalid API key or no API key provided. |
| 403 Forbidden | You do not have permission to access this resource or your account does not have the required subscription plan. |
| 404 Not Found | The requested resource does not exist or has been deleted. |
| 409 Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 422 Unprocessable Entity | The request was valid but could not be processed due to validation errors or invalid data. |
| 429 Too Many Requests | You have exceeded the rate limit for your subscription plan. Please wait before making another request. |
| 500 Internal Server Error | Something went wrong on our end. Please try again or contact support if the issue persists. |
Sending your first letter
The most common API use case is to create and send a letter. Calling this request will create and send a letter which will be posted in the next available postage window.
Parameters
| Parameter | Details | Description |
|---|---|---|
| test | body bool optional | Set to true to generate a sample PDF without dispatch or charge. |
| template | body int required | The ID of a template already set up on the platform. |
| recipient | body object required | Either an ID of an existing recipient or a new recipient array. e.g., recipient[title], recipient[company], recipient[firstname], recipient[lastname], recipient[address1], recipient[address2], recipient[city], recipient[postcode], recipient[country] and recipient[*] to use any custom data. |
| tags | body str optional | Comma-separated tags for your reference. |
Request Example
curl -X POST "https://api-eu1.stannp.com/v1/letters/create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"test": "true",
"template": "123456",
"recipient": {
"address1": "Unit 12 Taw Trade Park",
"address2": "Braunton Road",
"address3": "",
"city": "Barnstaple",
"county": "Devon",
"postcode": "EX31 1JZ",
"country": "GB"
},
"tags": "first_send,letter,123456"
}'
Response Example
{
"success": true,
"data": {
"pdf": "URL_PDF_LINK",
"id": 0,
"created": "YYYY-MM-DD HH:MM:SS",
"format": "A4",
"cost": "0.99",
"status": "test"
}
}