API Documentation | Stannp

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. You can specify a template or provide the content directly.

[POST] https://api-us1.stannp.com/v1/letters/create

Parameters

test	boolean	If set to true, a sample PDF file will be produced but the item will not be dispatched and no charge will be taken.
recipient	array	Either an ID of an existing recipient or a new recipient array.
template	int	An ID of a template already set up on the platform.
file	string	Alternatively to using the template or pages parameters, you can send a PDF/DOC file directly. Maximum of 10 pages.
duplex	boolean	Set to false if you only want to print on the front of each page. Defaults to true.
clearzone	boolean	If true, we will overlay clear zones with a white background. Defaults to true.
post_unverified	boolean	Default is true. If set to false, we will not post the item if the recipient address could not be verified.
tags	string	Comma-separated tags for your reference which you can search by in reporting.
addons	string	Use addon codes to upgrade your letter, e.g., FIRST_CLASS to send your letter using first-class postage.

Request

                <?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api-us1.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]' => "Doe",
        'recipient[address1]' => "1234 Maple Street",
        'recipient[address2]' => "Apt 101",
        'recipient[town]' => "Toronto",
        'recipient[zipcode]' => "M5G 1X8",
        'recipient[country]' => "CA",
        'tags' => "used.for.reporting",
        'addons' => "first_class"
    ),
    
));

$response = curl_exec($curl);

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

Response

{
    "success": true,
    "data": {
        "pdf": "https:\/\/www.stannp.com\/assets\/samples\/letter-sample-ca.pdf",
        "id": "1",
        "created": "2022-12-15T10:30:00+00:00",
        "format": "us-letter",
        "cost": "0.80",
        "status": "test"
    }
}

Post a Letter (Already Mail Merged)

Post a single letter that already has an address on the PDF file. Use this endpoint if you have already mail-merged your letter and it meets our design guidelines.

[POST] https://api-us1.stannp.com/v1/letters/post

Parameters

test	boolean	If set to true, a sample PDF file will be produced but the item will not be dispatched and no charge will be taken.
country	string	ISO alpha-2 country code, e.g., US, CA, GB, FR, DE.
pdf	string	A URL or binary file of the PDF file to print and post.
duplex	boolean	Defaults to true.
transactional	boolean	Use this for sensitive data. Defaults to false.
tags	string	Comma-separated tags for your reference which you can search by in reporting.
ocr	boolean	If set to true, we will try to read the address from the window clear zone and validate the address.

Request

                <?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api-us1.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' => "CA",
        'pdf' => "https://www.stannp.com/assets/samples/letter-sample-ca.pdf"
    ),
    
));

$response = curl_exec($curl);

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

Response

{
    "success": true,
    "data": {
        "pdf": "https:\/\/www.stannp.com\/assets\/samples\/letter-sample-ca-response.pdf",
        "id": "2",
        "created": "2022-12-15T11:00:00+00:00",
        "format": "letter",
        "cost": "0.85",
        "status": "test"
    }
}

Get a Single Letter

Obtain the mailpiece object for the letter ID specified.

[GET] https://api-us1.stannp.com/v1/letters/get/:id

Request

                <?php
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-us1.stannp.com/v1/letters/get/:id?api_key=" . API_KEY, false, $context);
$response = json_decode($result, true);

print_r($response);
?>

Response

{
    "success": true,
    "data": {
        "id": "16818220",
        "timestamp": "2022-12-15 12:30:00",
        "status": "delivered",
        "type": "letter",
        "format": "A4",
        "pdf_file": "https:\/\/dash.stannp.com\/api\/v1\/storage\/get\/port\/16818220\/pdfs\/sample-letter-ca.pdf",
        "country": "CA",
        "cost": "0.00"
    }
}

Cancel a Letter

Cancel a letter if it has not started processing yet.

[POST] https://api-us1.stannp.com/v1/letters/cancel

Parameters

id

int

The ID of the mailpiece item.

Request

                <?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api-us1.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);
?>

Response

{
    "success": true
}