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 Technical support

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 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 a 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 approved 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 must be 300dpi.

Therefore the dimension of the front image must 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 must be 343 x 248 pixels.

Dimension of the branding image must 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'.

What is the maximum length of the text?

Field	Max-Length	Min-Length
SENDER_TEXT	900	0
SENDER_ADDRESS	45	0
SENDER_ADDRESS_FIRSTNAME	75	2
SENDER_ADDRESS_LASTNAME	75	2
SENDER_ADDRESS_COMPANY	39	2
SENDER_ADDRESS_STREET	50	2
SENDER_ADDRESS_HOUSENR	5	0
SENDER_ADDRESS_ZIP	39	4
SENDER_ADDRESS_CITY	30	2
RECIPIENT_ADDRESS_TITLE	30	0
RECIPIENT_ADDRESS_FIRSTNAME	75	2
RECIPIENT_ADDRESS_LASTNAME	75	2
RECIPIENT_ADDRESS_COMPANY	39	2
RECIPIENT_ADDRESS_STREET	50	2
RECIPIENT_ADDRESS_HOUSENR	5	0
RECIPIENT_ADDRESS_ZIP	39	4
RECIPIENT_ADDRESS_CITY	30	2
RECIPIENT_ADDRESS_POBOX	5	0
RECIPIENT_ADDRESS_ADDITIONAL_INFO	75	0
BRANDING_TEXT_TEXT	250	0
BRANDING_TEXT_TEXTCOLOR	7	4
BRANDING_TEXT_BACKGROUND_COLOR	7	4
BRANDING_QR_ENCODED_TEXT	100	0
BRANDING_QR_ACCOMPANYING_TEXT	250	0
BRANDING_QR_TEXTCOLOR	7	4
BRANDING_QR_BACKGROUND_COLOR	7	4

How do we know when we have too much text?

The API responds with an appropriate warning e.g. «The length of sender text is invalid»

This is already described under «Error and warning messages»

What is the maximum length of a word?

This depends on the letters in the word. Generally speaking: The space for the sender text is 61 x 61px and the text is displayed with font = Arial, font size = 2.3pt, line height = 125%.

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

Footer

Additional links

Facebook Twitter [SocialMedia | instagram] Youtube LinkedIn Xing

Postcard API

Postcard API

Postcard API

Technical specifications of Postcard API

Postcard Elements

Postcard Resource Structure

Postcard Resource State Event Diagram

Common Sequence creating a postcard

Text and image formats

Text

What is the maximum length of the text?

How do we know when we have too much text?

What is the maximum length of a word?

Branding block

Branding text:

Branding image:

Banding QR-Tag with text:

Campaign API

Authentication

Request

Sample response

Error and warning messages

Footer

Additional links

Follow us