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://dash.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[town], recipient[postcode], 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.
pages optional The text content for each page of the letter. This can be a string containing basic HTML. Each page can be separated by sending an array for example: pages[0]="page 1"&pages[1]="page 2". This value is not required if a template or file is being used. Maximum of 10 pages.
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.
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://dash.stannp.com/api/v1/letters/create \
-u {API_KEY}: \
-d "test=true" \
-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[postcode]=AB12 3CD" \ -d "recipient[country]=GB"
define("API_KEY","YOUR API KEY");
$postdata = http_build_query(
  array(
  	'test' => "true",
  	'background' => "https://www.stannp.com/assets/samples/letter-heading.jpg" ,
  	'pages' => "Hello {firstname},<br><br>This is my first letter.",
  	'recipient[title]' => "Mr",   
  	'recipient[firstname]' => "Steve",
  	'recipient[lastname]' => "Parish",
  	'recipient[address1]' => "Unit 12 Taw Trade Park",
  	'recipient[address2]' => "Braunton Road",
  	'recipient[city]' => "Barnstaple",
  	'recipient[postcode]' => "EX31 1JZ",
  	'recipient[country]' => "GB"
  )
);
$opts = array('http' => array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
  )
);
$context  = stream_context_create($opts);
$result = file_get_contents("https://dash.stannp.com/api/v1/letters/create?api_key=".API_KEY, false, $context);
$response = json_decode($result,true);
print_r($response);
Response
{
   "success":true,
   "data":{
      "pdf":"https://www.stannp.com/assets/samples/letter-sample.pdf"
   }
}

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://dash.stannp.com/api/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.
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/letters/post \
-u {API_KEY}: \
-d "test=true" \
-d "country=GB" \
-d "pdf=https://www.stannp.com/assets/samples/letter-sample.pdf"
define("API_KEY","YOUR API KEY");
$postdata = http_build_query(
  array(
  	'test' => "true",
  	'country' => "GB",   
  	'pdf' => "https://www.stannp.com/assets/samples/letter-sample.pdf"
  )
);
$opts = array('http' => array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
  )
);
$context  = stream_context_create($opts);
$result = file_get_contents("https://dash.stannp.com/api/v1/letters/post?api_key=".API_KEY, false, $context);
$response = json_decode($result,true);
print_r($response);
Response
{
   "success":true,
   "data":{
      "pdf":"https://www.stannp.com/assets/samples/letter-sample.pdf"
   }
}

Create a batch of letters


https://dash.stannp.com/api/v1/letters/batch

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.
csv mandatory A csv file containing recipient addresses. The first row must contain column heading names. Column heading names should include the following: title, firstname, lastname, address1, address2, address3, city, postcode.

Extra column names can be included and used as template tags if using templates. These column names will always be made lower case and spaces will be replaced with underscores.
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.
pages optional The text content for each page of the letter. This can be a string containing basic HTML. Each page can be separated by sending an array for example: pages[0]="page 1"&pages[1]="page 2". This value is not required if a template or file is being used. Maximum of 10 pages.
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 or a URL to a file. Maximum of 10 pages.
Request
$ curl https://dash.stannp.com/api/v1/letters/batch \
-u {API_KEY}: \
-F "test=true" \
-F "csv=@/home/user/Desktop/data.csv"

Response
{
  "success": true,
  "data": {
    "cost": 0.84,
    "uk_matched": 2,
    "uk_not_matched": 0,
    "international": 0,
    "letters": [
      {
        "pdf": "https://stannp.blob.core.windows.net/pdf-production/1234-147fgfgf557142157b47a4366ef2-afb4e1sdf.pdf",
        "id": "215"
      },
      {
        "pdf": "https://stannp.blob.core.windows.net/pdf-production/12345-147144fgfg4657b47a44b64b8-283cfgf5db.pdf",
        "id": "216"
      }
    ]
  }
}

Get a single letter


https://dash.stannp.com/api/v1/letters/get/:id
Request
$ curl https://dash.stannp.com/api/v1/letters/get/16818210?api_key={API_KEY}
{
   "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://dash.stannp.com/api/v1/letters/cancel

Parameters

id mandatory The id of the mailpiece item.
Request
$ curl https://dash.stannp.com/api/v1/letters/cancel \
-u {API_KEY}: \
-d "id=12345"
define("API_KEY","YOUR API KEY");
$postdata = http_build_query(
  array(
  	'id' => "12345"
  )
);
$opts = array('http' => array(
    'method'  => 'POST',
    'header'  => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
  )
);
$context  = stream_context_create($opts);
$result = file_get_contents("https://dash.stannp.com/api/v1/letters/cancel?api_key=".API_KEY, false, $context);
$response = json_decode($result,true);
print_r($response);
Response
{
   "success":true
}