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://us.stannp.com/api/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[city], recipient[state], recipient[zipcode], recipient[country] and recipient[*] to use any custom data.
background optional A letter heading design or a file for the background of every page. This can be either a URL, a file or a base64 encoded string. Supported file types are JPG or PDF.
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://us.stannp.com/api/v1/letters/create \
-u {API_KEY}: \
-d "test=1" \ 
-d "background=https://www.stannp.com/assets/samples/letter-heading.jpg" \ 
-d "pages=Hello {firstname}, 

This is my first letter." \ -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[state]=NY" \ -d "recipient[zipcode]=AB12 3CD" \ -d "recipient[country]=GB"
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://us.stannp.com/api/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",
        'background' => "https://www.stannp.com/assets/samples/letter-heading.jpg",
        'pages' => "Hello {firstname}, 

This is my first letter.", 'recipient[title]' => "Mr", 'recipient[firstname]' => "John", 'recipient[lastname]' => "Smith", 'recipient[address1]' => "123 Sample Street", 'recipient[address2]' => "Sampleland", 'recipient[town]' => "Sampletown", 'recipient[state]' => "NY", 'recipient[zipcode]' => "AB12 3CD", 'recipient[country]' => "GB" ), )); $response = curl_exec($curl); curl_close($curl); print_r($response);
import requests

data = {
    'test': '1',
    'background': 'https://www.stannp.com/assets/samples/letter-heading.jpg',
    'pages': 'Hello {firstname}, 

This is my first letter.', 'recipient[title]': 'Mr', 'recipient[firstname]': 'John', 'recipient[lastname]': 'Smith', 'recipient[address1]': '123 Sample Street', 'recipient[address2]': 'Sampleland', 'recipient[town]': 'Sampletown', 'recipient[state]': 'NY', 'recipient[zipcode]': 'AB12 3CD', 'recipient[country]': 'GB' } response = requests.post('https://us.stannp.com/api/v1/letters/create?api_key={API_KEY}', data=data) print(response.text)
var client = new RestClient("https://us.stannp.com/api/v1/letters/create?api_key={API_KEY}");

var request = new RestRequest(Method.POST);

request.AddParameter("test", "1");
request.AddParameter("background", "https://www.stannp.com/assets/samples/letter-heading.jpg");
request.AddParameter("pages", "Hello {firstname}, 

This is my first letter."); 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[state]", "NY"); request.AddParameter("recipient[zipcode]", "AB12 3CD"); request.AddParameter("recipient[country]", "GB"); 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


https://us.stannp.com/api/v1/letters/get/:id
Request
$ curl https://us.stannp.com/api/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://us.stannp.com/api/v1/letters/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/letters/get/16818210?api_key={API_KEY}')
print(response.text)
var client = new RestClient("https://us.stannp.com/api/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 havn't started processing it yet.

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

Parameters

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

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