Direct Mail API

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 guidlines.

[POST] 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 or a URL to a file. 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.

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. See our guidlines.

[POST] 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.

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

[POST] 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"
      }
    ]
  }
}