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.
Parameter | Type | Description |
---|---|---|
test | optional | 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 | mandatory | Either an ID of an existing recipient or a new recipient array. |
template | optional | An ID of a template already set up on the platform. |
file | optional | Alternatively to using the template or pages parameters, you can send a PDF/DOC file directly. Maximum of 10 pages. |
duplex | optional | Set to false if you only want to print on the front of each page. Defaults to true. |
clearzone | optional | If true, we will overlay clear zones with a white background. Defaults to false. |
post_unverified | optional | Default is true. If set to false, we will not post the item if the recipient address could not be verified. |
tags | optional | Comma-separated tags for your reference which you can search by in reporting. |
addons | optional | Use addon codes to upgrade your letter, e.g., FIRST_CLASS to send your letter using first-class postage. |
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"
{ "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 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.
Parameter | Type | Description |
---|---|---|
test | optional | 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 | mandatory | ISO alpha-2 country code, e.g., US, CA, GB, FR, DE. |
file | optional | A URL or binary file of the PDF file to print and post. |
duplex | optional | Defaults to true. |
transactional | optional | Use this for sensitive data. Defaults to false. |
tags | optional | Comma-separated tags for your reference which you can search by in reporting. |
ocr | optional | If set to true, we will try to read the address from the window clear zone and validate the address. |
curl "https://api-us1.stannp.com/api/v1/letters/post" \
-u {API_KEY}: \
{ "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" } }
Obtain the mailpiece object for the letter ID specified.
Parameter | Type | Description |
---|---|---|
id | mandatory | The ID of the letter to retrieve. |
curl "https://api-us1.stannp.com/api/v1/letters/get/:id" \
-u {API_KEY}:
{ "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 if it has not started processing yet.
Parameter | Type | Description |
---|---|---|
id | mandatory | The ID of the mailpiece item. |
curl "https://api-us1.stannp.com/api/v1/letters/cancel" \
-u {API_KEY}: \
{ "success": true }