1. Introduction
  2. Authentication
    1. ProductToken
    2. AccountID
  3. Letters
    1. Create Letters
    2. Read Letters
    3. Update Letters
    4. Delete Letters
  4. Prices
    1. Read Prices
  5. Callbacks
    1. Create Callbacks
    2. Read Callbacks
    3. Update Callbacks
    4. Delete Callbacks

Introduction

The Letters api enables you to send physical messages to users.

You will need to provide a real-world delivery address, a printed letter with your content will be posted towards that endpoint.

Authentication

get your ProductToken

Authentication and authorization is done via a product token. You can obtain your product token from the messaging gateway app (https://www.cm.com/app/gateway/).

For all methods described in this api, the product token should be provided by including it in the X-CM-PRODUCTTOKEN header.

get your AccountID

In most methods you need to provide your AccountID. This is a guid that identifies your account. This identifier can be found on the url of the Letters application (https://www.cm.com/app/letters/), your AccountID guid will be automaticly completed on the url.

Letters

Behind the /letters/ endpoint you find all the methods to interact with your Letters.

Create Letters

Creating Letters can be done in two ways, one is by providing all the properties in text format, and the second is by providing the correctly formatted letter in PDF format.

from text

Post a JSON object like below

POST https://api.cm.com/letters/accounts/{accountId}/letters
{
    "express": true,
    "destination": "NL",
    "addresses":[{
        "recipient": "Recipient Name\nStreet and mailbox number\nzipcode , City , Country",
        "sender": "a single line sender-identifier"
    }],
    "subject": "Letter preamble",
    "message": "Content of the message,\n\nthis may contain utf-8 characters like ß and €, currently there is no emoji-support.\n\n\n\nKind Regards"
}

Letter object properties

Property Required Description
addresses required an array of recipients, object definition below, currently one address is supported
message required the letter content
destination required ISO country code of the destination address
scheduledate optional date (ISO 8601) to send the letter at a certain date (*)
subject optional subject line shown above the letter content
dateplace optional date and place of writing, placed on the top right above the letter content
fullcolor optional (boolean, default false) print in fullcolor
doublesided optional (boolean, default false) print both sides of a sheet
express optional (boolean, default false) send with priority, international only
registered optional (boolean, default false) use track and trace with Mailbox delivery notification, in Germany only
registeredMailbox optional (boolean, default false) use track and trace
registeredReceipt optional (boolean, default false) use track and trace with Recipient delivery verification notification, in Germany only

(*) scheduledate is currently a trigger to send instantly, there is no scheduling support yet.

Address object properties

Property Required Description
recipient required the full recipient address on one line with \n for new-lines
sender optional the full sender address on one line with \n for new-lines

from PDF file

Post a Form with the pdf file in a field. Any properties from the Letters object are valid in the form as well.

curl --request POST 'https://api.cm.com/letters/accounts/{accountID}/letters' \
--header 'X-CM-PRODUCTTOKEN: 00000000-0000-0000-0000-000000000000' \
--form 'pdf=@/path/to/file/letter-1.pdf' \
--form 'destination=NL' \
--form 'scheduledate=2020-02-22'

Read Letters

Find a list of all your Letters, or details about one of your specific letters.

all letters

GET https://api.cm.com/letters/accounts/{accountId}/letters

letter details

Get all the details for this specific letter.

GET https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}

letter price details

Get the price overview for this letter.

GET https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}/price

Update Letters

To make changes to a Letter that is not yet sent out, send a Letter object, defined above (at Create Letter), with the properties set up as you desire.

PUT https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}

Delete Letters

To remove a specific Letter.

DELETE https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}

Prices

Behind the /prices/ endpoint you find all the Price models we use.

Read Prices

GET https://api.cm.com/letters/accounts/{accountId}/prices

Read Country-specific Price

GET https://api.cm.com/letters/accounts/{accountId}/prices/{isoCode}

Callbacks

Behind the /callbacks/ endpoint you find all the callback-related methods.

Create Callbacks

Set up a Callback to receive a notification when the Status of a Letter changes. Currently only HTTP callbacks are supported.

POST https://api.cm.com/letters/accounts/{accountId}/callbacks
{
  "type": "http",
  "endpoint": "https://your.callback.url/endpoint/[LETTER]",
  "config": {
    "data": "{date=[RECEIVED_AT],status=[STATE]}"
  }
}

The properties type and endpoint are Required in this object. In the endpoint replace-keys will be replaced.

Replace key Description
[LETTER] Letter ID
[RECEIVED_AT] Status-change timestamp
[REFERENCE] The Reference you (could) have provided
[STATUS] The new Status
[TRACKINGCODE] The Tracking-code for Registered Letters

Available properties in the Callbacks object config property. All of these are optional. Some of these support replace-keys.

Config key Replace Description
method no Request method, default post
data yes Request content
query yes Query-string that will be used with the http-endpoint
headers yes Array of key-value pairs with header-name and value
contenttype no String determining the content-type, json or form or as provided, default json
verifySSL no boolean, default false

Read Callbacks

all callbacks

GET https://api.cm.com/letters/accounts/{accountId}/callbacks

callback details

GET https://api.cm.com/letters/accounts/{accountId}/callbacks/{callbackId}

Update Callbacks

To make changes to a Callback, send a Callback object, defined above (at Create Callbacks), with the properties set up as you desire.

PUT https://api.cm.com/letters/accounts/{accountId}/callbacks/{callbackId}

Delete Callbacks

DELETE https://api.cm.com/letters/accounts/{accountId}/callbacks/{callbackId}