X

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

                curl "https://api-us1.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]=Doe" \
-d "recipient[address1]=1234 Maple Street" \
-d "recipient[address2]=Apt 101" \
-d "recipient[town]=Toronto" \
-d "recipient[zipcode]=M5G 1X8" \
-d "recipient[country]=CA" \
-d "tags=used.for.reporting" \
-d "addons=first_class"

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

                curl "https://api-us1.stannp.com/v1/letters/post" \
-u {API_KEY}: \
-d "test=1" \
-d "country=CA" \
-d "pdf=https://www.stannp.com/assets/samples/letter-sample-ca.pdf"

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

                curl "https://api-us1.stannp.com/v1/letters/get/:id" \
-u {API_KEY}:

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

                curl "https://api-us1.stannp.com/v1/letters/cancel" \
-u {API_KEY}: \
-d "id=12345"

Response

{
    "success": true
}