Create a single postcard

This request will create a postcard and perform a mail merge to put the address and any variable data in place. Change the size parameter to select the format.
https://dash.stannp.com/api/v1/postcards/create

Parameters

size mandatory Either "A5", "A6" or "A5-ENV".
Download our A6 design guide.
Download our A5 design guide.
Download our enveloped A5 design guide.
test optional If test is set to true then a sample PDF file will be produced but the item will never be dispatched and no charge will be taken.
template optional An ID of a template already set up on the platform. Otherwise use front and back parameters.
recipient mandatory Either an ID of an existing recipient or a new recipient array.
eg: recipient[title], recipient[company], recipient[firstname], recipient[lastname], recipient[address1], recipient[address2], recipient[town], recipient[postcode], recipient[country] and recipient[*] to use any custom data.
front optional An image for the front. This can be either a URL, a file or a base64 encoded string. This must be supplied if a template is not being used. Supported file types are JPG or PDF.
back optional An image for the back. This can be either a URL, a file or a base64 encoded string. Supported file types are JPG or PDF.
message optional A message on the back of the card. If using a back image this message will be overlaid on top.
signature optional An image which will be placed in the signature location. The image can be either a URL or a file or a base64 encoded string. This must be a JPG file with a 768 x 118 pixels resolution.
padding optional A white border is added to the front of the postcard by default. You can set padding = 0 to remove the border if you want an edge to edge design.
post_unverified optional Default is true. If set to false then we will not post the item if the recipient address could not be verified.
clearzone optional True or False. If true we will overlay clear zones with a white background. Clearzones must be clear to keep a mailpiece machine readable. Defaults to true.
addons optional Use addon codes to upgrade your postcard. eg:
STOCK_350_UNCOATED to upgrade your paper stock to a thicker premium stock. Custom codes can be requested for bespoke postcards.
tags optional Comma separated tags which are for your reference which you can search by in reporting.
Request
$ curl https://dash.stannp.com/api/v1/postcards/create \
-u {API_KEY}: \
-d "test=true" \ 
-d "size=A6" \ 
-d "front=https://www.stannp.com/assets/samples/a6-postcard-front.jpg" \ 
-d "back=https://www.stannp.com/assets/samples/signature-example.jpg" \ 
-d "message=hello world" \ 
-d "recipient[title]=John" \ 
-d "recipient[firstname]=John" \ 
-d "recipient[lastname]=Smith" \ 
-d "recipient[address1]=Unit 1 Willow Tree Court" \ 
-d "recipient[address2]=Roundswell Business Park" \ 
-d "recipient[city]=Barnstaple" \ 
-d "recipient[postcode]=EX31 3TD" \ 
-d "recipient[country]=GB" \ 
-d "tags=used.for.reporting" \ 
-d "addons=first_class"
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://dash.stannp.com/api/v1/postcards/create?api_key={API_KEY}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array(
        'test' => "true",
        'size' => "A6",
        'front' => "https://www.stannp.com/assets/samples/a6-postcard-front.jpg",
        'back' => "https://www.stannp.com/assets/samples/signature-example.jpg",
        'message' => "hello world",
        'recipient[title]' => "John",
        'recipient[firstname]' => "John",
        'recipient[lastname]' => "Smith",
        'recipient[address1]' => "Unit 1 Willow Tree Court",
        'recipient[address2]' => "Roundswell Business Park",
        'recipient[city]' => "Barnstaple",
        'recipient[postcode]' => "EX31 3TD",
        'recipient[country]' => "GB",
        'tags' => "used.for.reporting",
        'addons' => "first_class"
    ),
));

$response = curl_exec($curl);

curl_close($curl);
print_r($response);
import requests

data = {
    'test': 'true',
    'size': 'A6',
    'front': 'https://www.stannp.com/assets/samples/a6-postcard-front.jpg',
    'back': 'https://www.stannp.com/assets/samples/signature-example.jpg',
    'message': 'hello world',
    'recipient[title]': 'John',
    'recipient[firstname]': 'John',
    'recipient[lastname]': 'Smith',
    'recipient[address1]': 'Unit 1 Willow Tree Court',
    'recipient[address2]': 'Roundswell Business Park',
    'recipient[city]': 'Barnstaple',
    'recipient[postcode]': 'EX31 3TD',
    'recipient[country]': 'GB',
    'tags': 'used.for.reporting',
    'addons': 'first_class'
}

response = requests.post('https://dash.stannp.com/api/v1/postcards/create?api_key={API_KEY}', data=data)
print(response.text)
var client = new RestClient("https://dash.stannp.com/api/v1/postcards/create?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("test", "true");
request.AddParameter("size", "A6");
request.AddParameter("front", "https://www.stannp.com/assets/samples/a6-postcard-front.jpg");
request.AddParameter("back", "https://www.stannp.com/assets/samples/signature-example.jpg");
request.AddParameter("message", "hello world");
request.AddParameter("recipient[title]", "John");
request.AddParameter("recipient[firstname]", "John");
request.AddParameter("recipient[lastname]", "Smith");
request.AddParameter("recipient[address1]", "Unit 1 Willow Tree Court");
request.AddParameter("recipient[address2]", "Roundswell Business Park");
request.AddParameter("recipient[city]", "Barnstaple");
request.AddParameter("recipient[postcode]", "EX31 3TD");
request.AddParameter("recipient[country]", "GB");
request.AddParameter("tags", "used.for.reporting");
request.AddParameter("addons", "first_class");

IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content)
Response
{
   "success":true,
   "data":{
      "pdf":"https://www.stannp.com/assets/samples/a6-postcard-sample.pdf",
      "id":"0",
      "created":"2020-12-17T15:42:22+00:00",
      "format":"A6",
      "cost":"0.78",
      "status":"test"
   }
}

Get a single postcard

Obtain the mailpiece object for the postcard id specified.
https://dash.stannp.com/api/v1/postcards/get/:id
Request
$ curl https://dash.stannp.com/api/v1/postcards/get/16818210 \
-u {API_KEY}:
define("API_KEY", "YOUR API KEY");
$opts = array(
    'http' => array(
        'method'  => 'GET',
        'header'  => 'Content-type: application/x-www-form-urlencoded'
    )
);
$context  = stream_context_create($opts);
$result = file_get_contents("https://dash.stannp.com/api/v1/postcards/get/16818210?api_key=" . API_KEY, false, $context);
$response = json_decode($result, true);

print_r($response);
import requests

response = requests.get('https://dash.stannp.com/api/v1/postcards/get/16818210?api_key={API_KEY}')
print(response.text)
var client = new RestClient("https://dash.stannp.com/api/v1/postcards/get/16818210?api_key={API_KEY}");

var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Console.WriteLine(response.Content);
Response
{
   "success":true,
   "data":
   {
        "id": "16818210",
        "timestamp": "2019-02-13 00:14:04",
        "status": "cancelled",
        "type": "postcard",
        "format": "A5",
        "pdf_file": "https://dash.stannp.com/api/v1/storage/get/port/1550016843/pdfs/15500168437775c63614bd88b1-d26cc45469-A5-K5aZSp.pdf",
        "dispatched": null,
        "country": "GB",
        "cost": "0.00",
        "insert_pdf": null,
        "insert_size": null,
        "addons": "",
        "tags": "",
        "postcode": "EX31 1JZ",
        "address": "Unit 12 Taw Trade Park"
   }
}

Cancel a postcard

You can cancel a postcard if we haven't started processing it yet.

https://dash.stannp.com/api/v1/postcards/cancel

Parameters

id mandatory The id of the mailpiece item.
Request
$ curl https://dash.stannp.com/api/v1/postcards/cancel \
-u {API_KEY}: \
-d "id=12345"
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://dash.stannp.com/api/v1/postcards/cancel?api_key={API_KEY}',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array(
        'id' => "12345"
    ),
));

$response = curl_exec($curl);

curl_close($curl);
print_r($response);
import requests

data = {
    'id': '12345'
}

response = requests.post('https://dash.stannp.com/api/v1/postcards/cancel?api_key={API_KEY}', data=data)
print(response.text)
var client = new RestClient("https://dash.stannp.com/api/v1/postcards/cancel?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("id", "12345");

IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content)
Response
{
    "success":true
}