Create a single letter

This request will create a letter and perform a mail merge to put the address and any variable data in place. Letters are folded and inserted into window envelopes.

You must ensure you adhere to our letter design guidelines.
https://api-eu1.stannp.com/v1/letters/create

Parameters

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.
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.
template optional An ID of a template already set up on the platform.
file optional Alternatively to using the template or pages parameters you could send a PDF / DOC file directly. This value can be either a binary file, a URL to a file or a base64 encoded string. Maximum of 10 pages.
duplex optional True or False. Duplex means we print on both sides of the letter. Set this to false if you want to only print on the front of each page. Defaults to true.
transactional optional True or False. Transactional mail is handled separatley from advertising mail and is not entilted to same discounts. Use this if your mail contains sensitive data. Defaults to false.
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.
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.
tags optional Comma separated tags which are for your reference which you can search by in reporting.
addons optional Use addon codes to upgrade your letter. eg:
FIRST_CLASS to send your letter using first class postage. Custom codes can be requested for bespoke mail pieces.
Request 
$ curl https://api-eu1.stannp.com/v1/letters/create \
-u {API_KEY}: \
-d "test=1" \ 
-d "file=https://www.stannp.com/assets/samples/letter-heading.pdf" \ 
-d "recipient[title]=Mr" \ 
-d "recipient[firstname]=John" \ 
-d "recipient[lastname]=Smith" \ 
-d "recipient[address1]=123 Sample Street" \ 
-d "recipient[address2]=Sampleland" \ 
-d "recipient[town]=Sampletown" \ 
-d "recipient[postcode]=AB12 3CD" \ 
-d "recipient[country]=GB" \ 
-d "tags=used.for.reporting" \ 
-d "addons=first_class"

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api-eu1.stannp.com/v1/letters/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' => "1",
        'file' => "https://www.stannp.com/assets/samples/letter-heading.pdf",
        'recipient[title]' => "Mr",
        'recipient[firstname]' => "John",
        'recipient[lastname]' => "Smith",
        'recipient[address1]' => "123 Sample Street",
        'recipient[address2]' => "Sampleland",
        'recipient[town]' => "Sampletown",
        'recipient[postcode]' => "AB12 3CD",
        'recipient[country]' => "GB",
        'tags' => "used.for.reporting",
        'addons' => "first_class"
    ),
));

$response = curl_exec($curl);

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

import requests

data = {
    'test': '1',
    'file': 'https://www.stannp.com/assets/samples/letter-heading.pdf',
    'recipient[title]': 'Mr',
    'recipient[firstname]': 'John',
    'recipient[lastname]': 'Smith',
    'recipient[address1]': '123 Sample Street',
    'recipient[address2]': 'Sampleland',
    'recipient[town]': 'Sampletown',
    'recipient[postcode]': 'AB12 3CD',
    'recipient[country]': 'GB',
    'tags': 'used.for.reporting',
    'addons': 'first_class'
}

response = requests.post('https://api-eu1.stannp.com/v1/letters/create?api_key={API_KEY}', data=data)
print(response.text)

var client = new RestClient("https://api-eu1.stannp.com/v1/letters/create?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("test", "1");
request.AddParameter("file", "https://www.stannp.com/assets/samples/letter-heading.pdf");
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[address2]", "Sampleland");
request.AddParameter("recipient[town]", "Sampletown");
request.AddParameter("recipient[postcode]", "AB12 3CD");
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/letter-sample.pdf",
      "id":"0",
      "created":"2020-12-17T15:42:22+00:00",
      "format":"letter",
      "cost":"0.78",
      "status":"test"
   }
}

Post a letter (already mail merged)

Post a single letter that already has an address on the PDF file.

You must ensure your address fits in our address zone. Failure to do so may result in the mailpiece not arriving. See our guidelines.
https://api-eu1.stannp.com/v1/letters/post

Parameters

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.
country mandatory ISO alpha 2 country code. For example “GB”, “US”, “FR” or “DE”.
pdf optional A URL or binary file of the pdf file to print and post. Design must be pre-approved for the address placement to prevent items not being posted.
file optional a PDF / DOC file directly. This value can be either a binary file, a URL to a file or a base64 encoded string.
duplex optional True or False. Duplex means we print on both sides of the letter. Set this to false if you want to only print on the front of each page. Defaults to true.
tags optional Comma separated tags which are for your reference which you can search by in reporting.
ocr optional True or False. If you set ocr to true. We will try to read the address from the window clear zone and validate the address to get the best rates and faster delivery.
transactional optional True or False. Transactional mail is handled separatley from advertising mail and is not entilted to same discounts. Use this if your mail contains sensitive data. Defaults to false.
addons optional Use addon codes to upgrade your letter. eg:
FIRST_CLASS to send your letter using first class postage. Custom codes can be requested for bespoke mail pieces.
Request 
$ curl https://api-eu1.stannp.com/v1/letters/post \
-u {API_KEY}: \
-d "test=1" \ 
-d "country=GB" \ 
-d "pdf=https://www.stannp.com/assets/samples/letter-sample.pdf"

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api-eu1.stannp.com/v1/letters/post?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' => "1",
        'country' => "GB",
        'pdf' => "https://www.stannp.com/assets/samples/letter-sample.pdf"
    ),
));

$response = curl_exec($curl);

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

import requests

data = {
    'test': '1',
    'country': 'GB',
    'pdf': 'https://www.stannp.com/assets/samples/letter-sample.pdf'
}

response = requests.post('https://api-eu1.stannp.com/v1/letters/post?api_key={API_KEY}', data=data)
print(response.text)

var client = new RestClient("https://api-eu1.stannp.com/v1/letters/post?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("test", "1");
request.AddParameter("country", "GB");
request.AddParameter("pdf", "https://www.stannp.com/assets/samples/letter-sample.pdf");

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

Get a single letter

Obtain the mailpiece object for the letter id specified.
https://api-eu1.stannp.com/v1/letters/get/:id
Request 
$ curl https://api-eu1.stannp.com/v1/letters/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://api-eu1.stannp.com/v1/letters/get/16818210?api_key=" . API_KEY, false, $context);
$response = json_decode($result, true);

print_r($response);

import requests

response = requests.get('https://api-eu1.stannp.com/v1/letters/get/16818210?api_key={API_KEY}')
print(response.text)

var client = new RestClient("https://api-eu1.stannp.com/v1/letters/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": "letter",
        "format": "A4",
        "pdf_file": "https://dash.stannp.com/api/v1/storage/get/port/1550016843/pdfs/15500168437775c63614bd88b1-d26cc45469-A4-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 letter

You can cancel a letter if we haven't started processing it yet.
https://api-eu1.stannp.com/v1/letters/cancel

Parameters

id mandatory The id of the mailpiece item.
Request 
$ curl https://api-eu1.stannp.com/v1/letters/cancel \
-u {API_KEY}: \
-d "id=12345"

$curl = curl_init();

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

var client = new RestClient("https://api-eu1.stannp.com/v1/letters/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
}