X

Create a single postcard

This request will create a postcard and perform a mail merge to put the address and any variable data in place.

[POST] https://api-us1.stannp.com/v1/postcards/create

Parameters

size mandatory Either "4x6" or "6x9" or "6x11".
Download our 4x6 design guide.
Download our 6x9 design guide.
Download our 6x11 design guide.
test 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 optional An ID of a template already set up on the platform. Otherwise use front and back parameters.
recipient mandatory 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.
front 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 or PDF.
back optional An image for the back. This can be either a URL, a file, or a base64 encoded string. Supported file types are JPG or PDF.
message optional A message on the back of the card. If using a back image, this message will be overlaid on top.
signature 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.
padding 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 optional Default is true. If set to false, we will not post the item if the recipient address could not be verified.
clearzone 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 true.
tags optional Comma-separated tags for your reference, which you can search by in reporting.
addons optional Use addon codes to upgrade your postcard. E.g., FIRST_CLASS for first-class mailing.

Request

                curl "https://api-us1.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 "tags=used.for.reporting" \
-d "addons=first_class"

Response

{
    "success": true,
    "data": {
        "pdf": "https:\/\/www.stannp.com\/assets\/samples\/a6-postcard-sample.pdf",
        "id": "0",
        "created": "2020-12-17T15:42:22+00:00",
        "format": "A6",
        "cost": "0.78",
        "status": "test"
    }
}

Get a single postcard

Obtain the mailpiece object for the postcard id specified.

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

Request

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

Response

{
    "success": true,
    "data": {
        "id": "16818211",
        "timestamp": "2019-10-30 00:14:04",
        "status": "cancelled",
        "type": "postcard",
        "format": "A6",
        "pdf_file": "https:\/\/dash.stannp.com\/api\/v1\/storage\/get\/port\/1550016843\/pdfs\/sample.pdf",
        "dispatched": null,
        "country": "GB",
        "cost": "0.00",
        "addons": "",
        "tags": "",
        "postcode": "AB12 3CD",
        "address": "123 Sample Street"
    }
}

Cancel a postcard

You can cancel a postcard if we haven't started processing it yet.

[POST] https://api-us1.stannp.com/v1/postcards/cancel

Parameters

id mandatory The id of the mailpiece item.

Request

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

Response

{
    "success": true
}