Create a single postcard


https://us.stannp.com/api/v1/postcards/create

Parameters

size mandatory Either "4x6" or "6x9" or "6x11".
Download our 4x6 design guide.
Download our 6x9 design guide.
Download our 6x11 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[city], recipient[state], recipient[zipcode], 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:
FIRST_CLASS to send your letter using first class postage. Custom codes can be requested for bespoke mail pieces.
tags optional Comma separated tags which are for your reference which you can search by in reporting.
Request
$ curl https://us.stannp.com/api/v1/postcards/create \
-u {API_KEY}: \
-d "test=true" \ 
-d "size=4x6" \ 
-d "front=https://www.stannp.com/assets/samples/a6-postcard-front.jpg" \ 
-d "message=hello world" \ 
-d "signature=https://www.stannp.com/assets/samples/signature-example.jpg" \ 
-d "recipient[title]=Mr" \ 
-d "recipient[firstname]=John" \ 
-d "recipient[lastname]=Smith" \ 
-d "recipient[address1]=123 Sample street" \ 
-d "recipient[city]=Sampletown" \ 
-d "recipient[zipcode]=12345" \ 
-d "recipient[country]=US"
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://us.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' => "4x6",
        'front' => "https://www.stannp.com/assets/samples/a6-postcard-front.jpg",
        'message' => "hello world",
        'signature' => "https://www.stannp.com/assets/samples/signature-example.jpg",
        'recipient[title]' => "Mr",
        'recipient[firstname]' => "John",
        'recipient[lastname]' => "Smith",
        'recipient[address1]' => "123 Sample street",
        'recipient[city]' => "Sampletown",
        'recipient[zipcode]' => "12345",
        'recipient[country]' => "US"
    ),
));

$response = curl_exec($curl);

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

data = {
    'test': 'true',
    'size': '4x6',
    'front': 'https://www.stannp.com/assets/samples/a6-postcard-front.jpg',
    'message': 'hello world',
    'signature': 'https://www.stannp.com/assets/samples/signature-example.jpg',
    'recipient[title]': 'Mr',
    'recipient[firstname]': 'John',
    'recipient[lastname]': 'Smith',
    'recipient[address1]': '123 Sample street',
    'recipient[city]': 'Sampletown',
    'recipient[zipcode]': '12345',
    'recipient[country]': 'US'
}

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

var request = new RestRequest(Method.POST);

request.AddParameter("test", "true");
request.AddParameter("size", "4x6");
request.AddParameter("front", "https://www.stannp.com/assets/samples/a6-postcard-front.jpg");
request.AddParameter("message", "hello world");
request.AddParameter("signature", "https://www.stannp.com/assets/samples/signature-example.jpg");
request.AddParameter("recipient[title]", "Mr");
request.AddParameter("recipient[firstname]", "John");
request.AddParameter("recipient[lastname]", "Smith");
request.AddParameter("recipient[address1]", "123 Sample street");
request.AddParameter("recipient[city]", "Sampletown");
request.AddParameter("recipient[zipcode]", "12345");
request.AddParameter("recipient[country]", "US");

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

Get a single postcard


https://us.stannp.com/api/v1/postcards/get/:id
Request
$ curl https://us.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://us.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://us.stannp.com/api/v1/postcards/get/16818210?api_key={API_KEY}')
print(response.text)
var client = new RestClient("https://us.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": "16818211",
        "timestamp": "2019-10-30 00:14:04",
        "status": "cancelled",
        "type": "postcard",
        "format": "4x6",
        "pdf_file": "https://dash.stannp.com/api/v1/storage/get/port/1550016843/pdfs/15500168437775c63614bd88b1-d26cc45469-A5-K5aZSp.pdf",
        "dispatched": null,
        "country": "US",
        "cost": "0.00",
        "addons": "",
        "tags": "",
        "postcode": "12345",
        "address": "123 Sample Street"
   }
}

Cancel a postcard

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

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

Parameters

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

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://us.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://us.stannp.com/api/v1/postcards/cancel?api_key={API_KEY}', data=data)
print(response.text)
var client = new RestClient("https://us.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
}