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