Postcard API

User navigation



Language navigation

Postcard API

Close

Postcard API

Technical specifications of Postcard API


Bring joy to others by sending postcards and turn customers into ambassadors: with the “Postcard API” digital interface, your customers can send individual postcards – via your website, your app or with a photo booth at an event. Swiss Post takes care of printing and mailing the postcards.

With “Postcard API” from Swiss Post, your customers can send individual postcards – complete with your company branding – and become your ambassadors. All you need is a connection to our digital interface. After the initial programming of the connection, you can use the Postcard API for the communication purposes of your choice. From a photo booth at a company event to a large-scale marketing campaign: postcards never fail to attract attention and generate affinity. It is up to you to decide how much branding you want to use to present your company on the postcard. You can also determine which communication channel your customers will use to access the postcard design process. There is a wide range of possibilities, such as via a link on your company website, an app or a Facebook plug-in.

Detailed information and contact

Postcard Elements

Swagger Documentation

Postcard Resource Structure

A post card resource has the following structure:

Postcard Resource State Event Diagram

Common Sequence creating a postcard

  • Check if there are available postcards to send - see Campaign API
  • Create a Post card resource (POST /postcards) minimally providing the recipientAddress. If no senderAddress is preconfigured in the campaign configuration (task by Swiss Post) a senderAddress has to be provided also.
  • Add an base64 encoded image (PUT /postcards/{cardKey}/image).
  • Add a branding block (PUT /postcards/{cardKey}/branding/text) /  (PUT /postcards/{cardKey}/branding/image) / (PUT /postcards/{cardKey}/branding/qrtag)(optional)
  • Add an base64 encoded stamp image (PUT /postcards/{cardKey}/branding/stamp) (optional).
  • Set the approval for printing the post card (POST /postcards/{cardKey}/approval)

A created postcard that is not confirmed within 60 minutes will be deleted.

Text and image formats

Supported image formats are JPEG and PNG (colour mode CYMK is not allowed) for uploading as image-file via the PUT /postcards/{cardKey}/image request.

A postcard has the a A6 form factor. For the production a 3mm overlap of the image on all sides is generated. The print resolution is 300dpi.

Therefore the dimension of the front image should be 1819 x 1311 pixels.

A image that has not the needed dimensions will be automatically proportionally scaled and trimmed.

If an image has a lower resolution than the optimal resolution the client receives a warning. However the post card will be produced anyway if the client set the approval on the post card. Higher resolutions will be downscaled to the optimal resolution because there will be no gain in quality in the print production.

Dimension of the stamp image should be 343 x 248 pixels.

Dimension of the branding image should be 777 x 295 pixels.

Text

Text has to be UTF-8 encoded and can only contain characters from the code page CP850. If other characters are included an ENCODING warning is raised and there is no guaranty that all characters get printed faultlessly.

Linebreaks in a text element has to be encoded with '\n'.

Branding block

There are three possible types of an branding block on a post card. The types cannot be combined on one postcard:

Branding text:

PUT /postcards/{cardKey}/branding/text

Branding image:

PUT /postcards/{cardKey}/branding/image

Banding QR-Tag with text:

PUT /api/v1/postcards/{cardKey}/branding/qrtag

PUT /postcards/{cardKey}/branding/text

Campaign API

The campaign API allows you to get a statistic about your campaign quota. You can request the quota, the number of created post cards and the number of available post cards.

This allows you to verify if there are available post cards before giving your user the ability to create a post card.

Recommendation: before creating a postcard resource verify if there are available postcards to send. The number of available postcards are listed in the attribute "freeToSendPostcards" - see the following sample of an response to a campaigns API request.

Swagger Documentation

{
    "campaignKey": "b5d9d195-505b-48f5-93bc-fbc503e9fba8",
    "quota": 20000,
    "sendPostcards": 2566,
    "freeToSendPostcards": 17434
}

Authentication

The API is secured via the OAuth 2.0 client credential flow.

More information: RFC 6749 - Client Credentials Grant.

Request
Auth URL provided following contract signing
Access Token URL provided following contract signing

An access token has to be requested with the following key-value pairs in a POST request (set Content-Type to "application/x-www-form-urlencoded"):

key
value
client_id
provided following contract signing
client_secret
provided following contract signing
scope
PCCAPI
grant_type
client_credentials
Sample response
{ "access_token": "n0xtJFWREwWhAq_Lzq6ahROIcc5N59l-SN3Yi0TXwxUuQ5yVpYm-kY8iRB1byc57rtmtJivH7lhlP11CX taoiE2Jh6y7fHn6Lqf0NJ1ONL7fxrkPpqIENDsprGMfXjC2.CMeSDXXJ5NylTWXX5Li-mM.1yLQ_q7KYZP.UMAzyj_km8nZayw brrtqBH4oeMG9hFEcerxVv9yPXD0376bJOJQRyZT6bSuiHyzJxtIcMy3Tlg8ZaU6fRm.jGxjulisJ6x_STG0zK1nI16W0bJGit PiDStG6bTED4XHriOLZUPUSZDxcjnm2JeTywgmncnrDReteJSe7BuHI6lCYTD9S5SZiK24u67vcFS8xVtwZyl7YM1zN64r1BSR sy4icGeMSKowirMRpm0wZ40xYMzABh5baP-TUvvJPlLAsF-CZo6RuWNkJZATR4N7CPXlzx_YemXc32-FY08F6go9wCa-aFDAFZ BRXJc8Ds3ACsjhy.UnYPlWoDOrOellexv11QIoz.Pqrohn7jMcWxyTumtDroVsECaohXllLUvUBTufa8Abl162Rc4pXuI1Pcm. eL22Lx.A6VLRgu28Lm.wfszskMbfVVFLh7-iZeuFESU-GcEbt.03-DbICraUH1QRA_0pHUuulQTpK_F-v29FIfM-8_Zq4-hMF. 7W2r6o_I-bZlyDr_OavG93EjSq9L_21q7pLyL7lrVS_cjinQDW_UFRk26vuBsTrzYsHm3U7B8qNxW3w7TFQ_VPJ8hDRqOb4VFn Gp1u1eMFRxgR9HWO3ccw-NPPxJJja.Ipqb2b8tV1CjQUmomLzcvWefH3bE6QM.iq4ksky5F3iFLuO_rIAAgfGQ8b-z53F3jeU9 _ab7gwcPIq0fIPpG81H64S-.l4MJ1wjvILLM_jlqZHf85K8LSXZH1CMoMg0yMRmgR2rF38AfIKmVcc9-aFZAJMZRJzJaAf3AaH b1-g3LwPL073oG8QDem5LZ0mXPSCWP47nODNBq1DDTChRnnJZ8W_uWR0Yj7wOzBwrVjpumKCCRBhf2q2y96hU-FLiRR7fZ6KG1 4gZcaFcCRrQYKa5j_rqH3bne_ZnigEl2", "token_type": "Bearer", "expires_in": 60 }

Use the returned Bearer token in the request header to access the API within the time limit returned in the expires_in attribute.

key
value
Authorization
Bearer n0xtJFWREwWhAq_Lzq6ahROIcc5N59l-SN3Yi0TXwxUuQ5yVpYm-kY8iRB1byc57rtmtJivH7lhlP11CX...

As an additional key for creating an post card resource a campaign key will be provided to you upon contract signing. For more detail see the swagger documentation POST /api/v1/postcards

Error and warning messages

Errors and warnings are returned in the following format:

{
    "cardKey": "0fb4efdf-e8b1-4593-a20c-39ab7fc6bb36",
    "errors": [
      {
        "code": 1006,
        "description": "Recipient address is required"
      },
      {
        "code": 1007,
        "description": "Front image is required"
      }
    ],
    "warnings": [
      {
        "code": 1109,
        "description": "The length of sender text is invalid"
      }
}

Important: be aware that the status code of a request can be 200 but the response contains errors and warnings. Do not treat a status code 200 as a successful call per se. Always evaluate the error and warning arrays.

Missing required fields Code
Description
NAME_REQUIRED
1000
The name is required
FIRSTNAME_REQUIRED
1001
The first name is required
STREET_REQUIRED
1002
The street is required
ZIP_REQUIRED
1003
The zip is required
CITY_REQUIRED
1004
The city is required
NAMES_COMBINATION_REQUIRED
1005
Name/ first name or company is required
SENDER_ADDRESS_REQUIRED
1008
Sender address is required
RECIPIENT_ADDRESS_REQUIRED
1006
Recipient address is required
FRONT_IMAGE_REQUIRED
1007
Front image is required
Data validation messages
Code
Description
TITLE_LENGTH_INVALID
1100
The length of title is invalid
NAME_LENGTH_INVALID
1101
The length of name is invalid
FIRSTNAME_LENGTH_INVALID
1102
The length of first name is invalid
COMPANY_LENGTH_INVALID
1103
The length of company is invalid
STREET_LENGTH_INVALID
1104
The length of street is invalid
HOUSENR_LENGTH_INVALID
1105
The length of houseNumber is invalid
ZIP_LENGTH_INVALID
1106
The length of zip is invalid
CITY_LENGTH_INVALID
1107
The length of city is invalid
POBOX_LENGTH_INVALID
1108
The length of poBox is invalid
SENDER_TEXT_LENGTH_INVALID
1109
The length of sender text is invalid
BRANDING_TEXT_LENGTH_INVALID
1110
The length of branding text is invalid
BRANDING_TEXT_COLOR_LENGTH_INVALID
1111
The length of branding text color is invalid
BRANDING_BG_COLOR_LENGTH_INVALID
1112
The length of branding background color is invalid
BRANDING_ENCODED_TEXT_LENGTH_INVALID
1113
The length of branding encoded text is invalid
Logical data validation messages
Code
Description
NAMES_COMBINATION_NOT_ALLOWED
1200
The combination last name/ first name and company is not allowed
NAME_OVERRIDE_NOT_ALLOWED
1201
The name can't be overwritten
FIRSTNAME_OVERRIDE_NOT_ALLOWED
1202
The first name can't be overwritten
COMPANY_OVERRIDE_NOT_ALLOWED
1203
The company can't be overwritten
STREET_OVERRIDE_NOT_ALLOWED
1204
The street can't be overwritten
HOUSENR_OVERRIDE_NOT_ALLOWED
1205
The houseNr can't be overwritten
ZIP_OVERRIDE_NOT_ALLOWED
1206
The zip can't be overwritten
CITY_OVERRIDE_NOT_ALLOWED
1207
The city can't be overwritten
POBOX_OVERRIDE_NOT_ALLOWED
1208
The poBox can't be overwritten
TITLE_OVERRIDE_NOT_ALLOWED
1209
The title can't be overwritten
BRANDING_TEXT_OVERRIDE_NOT_ALLOWED
1210
The branding text can't be overwritten
BRANDING_TEXT_COLOR_OVERRIDE_NOT_ALLOWED
1211
The branding text color can't be overwritten
BRANDING_BG_COLOR_OVERRIDE_NOT_ALLOWED
1212
The branding background color can't be overwritten
BRANDING_QR_TEXT_OVERRIDE_NOT_ALLOWED
1213
The bradning qr code can't be overwritten
Text encoding messages
Code
Description
SENDER_TEXT_INVALID_ENCODING
1300
Sender text has invalid encoding
NAME_INVALID_ENCODING
1301
Name has invalid encoding
FIRSTNAME_INVALID_ENCODING
1302
First name has invalid encoding
STREET_INVALID_ENCODING
1303
Street has invalid encoding
CITY_INVALID_ENCODING
1304
City has invalid encoding
TITLE_INVALID_ENCODING
1305
Title has invalid encoding
COMPANY_INVALID_ENCODING
1306
Company has invalid encoding
BRANDING_TEXT_INVALID_ENCODING
1307
Branding text has invalid encoding
BRANDING_QR_INVALID_ENCODING
1308
Branding qr code has invalid encoding
Logical brandig block validation messages
Code
Description
BRANDING_COMBINATION_NOT_ALLOWED
1400
The combination of branding text/qr tag and branding image is not allowed. In this case no branding will be printed.
TEXT_COLOR_INVALID
1401
Branding text color has an invalid hex value example #FFFFFF
BG_COLOR_INVALID
1402
Branding background color has an invalid hex value example #FFFFFF
BRANDING_LINK_INVALID
1403
Branding QR link is invalid.
Campaign messages
Code
Description
CAMPAIGN_QUOTA_EXCEEDED
2000
Campaign quota exceeded
CAMPAIGN_EXPIRED
2010
The end date of campaign is reached
CAMPAIGN_NOT_STARTED
2020
The campaign has not yet started
CAMPAIGN_NOT_ACTIVE
2030
The campaign is not active
CAMPAIGN_NOT_FOUND
4000
Campaign not found
CAMPAIGN_CONFIG_NOT_FOUND
4001
Campaign configuration not found
BRANDING_NOT_FOUND
4002
Branding for campaign not found
POSTCARD_NOT_FOUND
4003
Postcard not found
Generall messages
Code
Description
ENCODING_VIOLATION
5000
Violation of encoding rules
FILE_FORMAT_NOT_SUPORTED
5010
Given file format is not supported
BAD_RESOLUTION
5020
Image: higher resolution recommended
PERIPHERAL_SYSTEM_NOT_AVAILABLE
5050
Peripheral system is not available
Process messages
Code
Description
POSTCARD_ALREADY_APPROVED
6000
The given postcard is already approved