Create, retrieve, and manage letters. Send personalised letters using templates, custom PDFs, or pre-merged documents.
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 | Details | Description |
|---|---|---|
| test | body bool 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 | body mixed required | Either an ID of an existing recipient or a new recipient array. e.g., recipient[title], recipient[company], recipient[firstname], recipient[lastname], recipient[address1], recipient[address2], recipient[city], recipient[postcode], recipient[country] and recipient[*] to use any custom data. |
| template | body int optional | An ID of a template already set up on the platform. |
| file | body file optional | Alternatively to using the template or pages parameters, you can send a PDF/DOC file directly. Maximum of 10 pages. |
| size | body str optional | The paper format. Either "A4" or "US-LETTER". Defaults to "A4" for EU/UK accounts and "US-LETTER" for US accounts. |
| duplex | body bool optional | Set to false if you only want to print on the front of each page. Defaults to true. |
| clearzone | body bool optional | If true, we will overlay clear zones with a white background. Defaults to true. |
| post_unverified | body bool optional | Default is true. If set to false, we will not post the item if the recipient address could not be verified. |
| tags | body str optional | Comma-separated tags for your reference which you can search by in reporting. |
| addons | body str optional | Use addon codes to upgrade your letter. Available codes: FIRST_CLASS (first-class postage), C4_ENVELOPE (C4 envelope), CONFIDENTIAL (confidential envelope), STOCK_120 (120 GSM paper). Comma-separate multiple addons, e.g., FIRST_CLASS,CONFIDENTIAL. |
curl "https://api-eu1.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]=Smith" \
-d "recipient[address1]=123 Sample Street" \
-d "recipient[address2]=Sampleland" \
-d "recipient[town]=Sampletown" \
-d "recipient[postcode]=AB12 3CD" \
-d "recipient[country]=GB" \
-d "recipient[url]=www.example.com/landing-page" \
-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": "2024-01-15 10:30:00",
"format": "A4",
"cost": "0.81",
"status": "test"
}
}test=true). In live mode, the response includes additional fields: type, title, firstname, lastname, company, address1-address3, city, county, postcode, country, addons, tags, tracking_ref, production_ref, dispatched, updated, transactional, and class.Post a single letter that already has an address on the PDF file. The PDF must contain the recipient address in a machine-readable format — the API will use OCR to extract the address from the document. Use this endpoint if you have already mail-merged your letter and it meets our design guidelines.
| Parameter | Details | Description |
|---|---|---|
| test | body bool 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 | body str required | ISO alpha-2 country code, e.g., US, CA, GB, FR, DE. |
body file optional | A URL or binary file of the PDF file to print and post. Also accepts the parameter name "file". | |
| size | body str optional | The paper format. Either "A4" or "US-LETTER". Defaults to "A4" for EU/UK accounts and "US-LETTER" for US accounts. |
| duplex | body bool optional | Defaults to true. |
| transactional | body bool optional | Use this for sensitive data. Defaults to false. |
| tags | body str optional | Comma-separated tags for your reference which you can search by in reporting. |
| addons | body str optional | Use addon codes to upgrade your letter. Available codes: FIRST_CLASS (first-class postage), C4_ENVELOPE (C4 envelope), CONFIDENTIAL (confidential envelope), STOCK_120 (120 GSM paper). Comma-separate multiple addons, e.g., FIRST_CLASS,CONFIDENTIAL. |
curl "https://api-eu1.stannp.com/v1/letters/post" \
-u {API_KEY}: \
-d "test=1" \
-d "country=GB" \
-d "pdf=https://www.stannp.com/assets/samples/letter-sample-abcdefg-12356.pdf"{
"success": true,
"data": {
"pdf": "https://www.stannp.com/assets/samples/letter-sample.pdf",
"id": 0,
"created": "2024-01-15 10:30:00",
"format": "A4",
"cost": "0.81",
"status": "test"
}
}test=true). In live mode, the response includes additional fields: type, title, firstname, lastname, company, address1-address3, city, county, postcode, country, addons, tags, tracking_ref, production_ref, dispatched, updated, transactional, and class.Obtain the mailpiece object for the letter ID specified. The response includes status, tracking, and cost information.
curl "https://api-eu1.stannp.com/v1/letters/get/:id" \
-u {API_KEY}:{
"success": true,
"data": {
"id": 16818210,
"account_id": 5,
"timestamp": "2019-02-13 00:14:04",
"status": "cancelled",
"type": "letter",
"format": "A4",
"pdf_file": "https://api-eu1.stannp.com/v1/storage/get/port/1550016843/pdfs/15500168437775c63614bd88b1-d26cc45469-A4-K5aZSp.pdf",
"dispatched": null,
"country": "GB",
"cost": 0,
"addons": "",
"tags": "",
"postcode": "AB12 3CD",
"template_id": 0,
"campaign_id": 0,
"recipient_id": 0,
"transactional": 0,
"class": 0,
"updated": "2019-02-13 00:14:04",
"mailpiece_id": 16818210,
"firstname": "John",
"lastname": "Smith",
"address1": "123 Sample Street",
"address2": "",
"address3": "",
"city": "Sampletown",
"county": "",
"tracking_ref": null,
"tracking": []
}
}Cancel a letter if it has not started processing yet.
| Parameter | Details | Description |
|---|---|---|
| id | int required | The ID of the mailpiece item. |
curl "https://api-eu1.stannp.com/v1/letters/cancel" \
-u {API_KEY}: \
-d "id=12345"{
"success": true,
"data": 1
}