Create, retrieve, and manage postcards. Send personalised postcards to recipients using templates or custom designs.
This request will create a postcard and perform a mail merge to put the address and any variable data in place.
| Parameter | Details | Description |
|---|---|---|
| size | body str optional | Either "A6", "A5", "A5-ENV", or "A5-PORT". Defaults to "A6" if not specified. Note: A5-PORT (A5 Portrait) is available for single sends; campaign approval via API may have limitations. Download our A6 design guide. Download our A5 design guide. Download our A5-ENV design guide. |
| test | body bool optional | If test is set to true then a sample PDF file will be produced but the item will never be dispatched and no charge will be taken. |
| template | body int optional | An ID of a template already set up on the platform. Otherwise use front and back parameters. |
| 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. |
| message | body str optional | A message on the back of the card. If using a back image, this message will be overlaid on top. |
| signature | body file optional | An image placed in the signature location. The image can be either a URL, a file, or a base64 encoded string. This must be a JPG file with a 768 x 118 pixels resolution. |
| front | body file optional | An image for the front. This can be either a URL, a file, or a base64 encoded string. This must be supplied if a template is not being used. Supported file types are JPG, PNG, or PDF. |
| back | body file optional | An image for the back. This can be either a URL, a file, or a base64 encoded string. Supported file types are JPG, PNG, or PDF. |
| padding | body int optional | A white border is added to the front of the postcard by default. Set padding = 0 to remove the border if you want an edge-to-edge design. |
| 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. |
| clearzone | body bool optional | True or False. If true, we will overlay clear zones with a white background. Clear zones must be clear to keep a mailpiece machine-readable. Defaults to false. |
| return_address | body str optional | A custom return address to print on the postcard. |
| 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 postcard. Available codes: FIRST_CLASS (first-class postage), STOCK_350_SILK (350 GSM silk card), STOCK_350_UNCOATED (350 GSM uncoated card). Comma-separate multiple addons. |
curl "https://api-eu1.stannp.com/v1/postcards/create" \
-u {API_KEY}: \
-d "test=true" \
-d "size=A6" \
-d "front=https://www.stannp.com/assets/samples/a6-postcard-front.webp" \
-d "back=https://www.stannp.com/assets/samples/signature-example.webp" \
-d "message=hello world" \
-d "recipient[title]=Mr" \
-d "recipient[firstname]=John" \
-d "recipient[lastname]=Smith" \
-d "recipient[address1]=123 Sample Street" \
-d "recipient[city]=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/a6-postcard-sample.pdf",
"id": 0,
"created": "2024-01-15T10:30:00+00:00",
"format": "A6",
"cost": "0.88",
"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 postcard id specified.
curl "https://api-eu1.stannp.com/v1/postcards/get/:id" \
-u {API_KEY}:{
"success": true,
"data": {
"id": 16818211,
"timestamp": "2019-10-30 00:14:04",
"status": "cancelled",
"type": "postcard",
"format": "A6",
"pdf_file": "https://api-eu1.stannp.com/v1/storage/get/port/1550016843/pdfs/sample.pdf",
"dispatched": null,
"country": "GB",
"cost": 0,
"addons": "",
"tags": "",
"template_id": 0,
"campaign_id": 0,
"recipient_id": 0,
"firstname": "John",
"lastname": "Smith",
"address1": "123 Sample Street",
"address2": "",
"address3": "",
"city": "Sampletown",
"county": "",
"postcode": "AB12 3CD",
"tracking_ref": null,
"transactional": 0,
"class": 0,
"updated": "2019-10-30 00:14:04",
"mailpiece_id": 16818211,
"tracking": []
}
}You can cancel a postcard if we haven't started processing it yet.
| Parameter | Details | Description |
|---|---|---|
| id | int required | The id of the mailpiece item. |
curl "https://api-eu1.stannp.com/v1/postcards/cancel" \
-u {API_KEY}: \
-d "id=12345"{
"success": true,
"data": 1
}