Direct Mail API - Letters

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/api/v1/letters/create

Parameters

ParameterTypeDescription
testoptionalIf set to true, a sample PDF file will be produced but the item will not be dispatched and no charge will be taken.
recipientmandatoryEither an ID of an existing recipient or a new recipient array.
templateoptionalAn ID of a template already set up on the platform.
fileoptionalAlternatively to using the template or pages parameters, you can send a PDF/DOC file directly. Maximum of 10 pages.
duplexoptionalSet to false if you only want to print on the front of each page. Defaults to true.
clearzoneoptionalIf true, we will overlay clear zones with a white background. Defaults to false.
post_unverifiedoptionalDefault is true. If set to false, we will not post the item if the recipient address could not be verified.
tagsoptionalComma-separated tags for your reference which you can search by in reporting.
addonsoptionalUse addon codes to upgrade your letter, e.g., FIRST_CLASS to send your letter using first-class postage.

Request Example

        curl "https://api-us1.stannp.com/api/v1/letters/create" \
-u {API_KEY}: \
-d "test=true" \
-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 Example

{
  "success": true,
  "data": {
    "pdf": "https://www.stannp.com/assets/samples/letter-sample-12345-12345-abcdeg.pdf",
    "id": "0",
    "created": "2022-10-01T15:42:22+00:00",
    "format": "us-letter",
    "cost": "0.76",
    "status": "test"
  }
}

Post a single letter

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/api/v1/letters/post

Parameters

ParameterTypeDescription
testoptionalIf set to true, a sample PDF file will be produced but the item will not be dispatched and no charge will be taken.
countrymandatoryISO alpha-2 country code, e.g., US, CA, GB, FR, DE.
fileoptionalA URL or binary file of the PDF file to print and post.
duplexoptionalDefaults to true.
transactionaloptionalUse this for sensitive data. Defaults to false.
tagsoptionalComma-separated tags for your reference which you can search by in reporting.
ocroptionalIf set to true, we will try to read the address from the window clear zone and validate the address.

Request Example

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

    

Response Example

{
  "success": true,
  "data": {
    "pdf": "https://www.stannp.com/assets/samples/letter-sample.pdf",
    "id": "0",
    "created": "2022-12-01T15:42:22+00:00",
    "format": "letter",
    "cost": "0.78",
    "status": "test"
  }
}

Get a single letter

Obtain the mailpiece object for the letter ID specified.

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

Parameters

ParameterTypeDescription
idmandatoryThe ID of the letter to retrieve.

Request Example

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

Response Example

{
  "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/api/v1/letters/cancel

Parameters

ParameterTypeDescription
idmandatoryThe ID of the mailpiece item.

Request Example

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

    

Response Example

{
  "success": true
}