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 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.
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.
Behind the /letters/ endpoint you find all the methods to interact with your 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.
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 |
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'Find a list of all your Letters, or details about one of your specific letters.
GET https://api.cm.com/letters/accounts/{accountId}/lettersGet all the details for this specific letter.
GET https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}Get the price overview for this letter.
GET https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}/priceTo 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}To remove a specific Letter.
DELETE https://api.cm.com/letters/accounts/{accountId}/letters/{letterId}Behind the /prices/ endpoint you find all the Price models we use.
GET https://api.cm.com/letters/accounts/{accountId}/pricesGET https://api.cm.com/letters/accounts/{accountId}/prices/{isoCode}Behind the /callbacks/ endpoint you find all the callback-related methods.
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 |
GET https://api.cm.com/letters/accounts/{accountId}/callbacksGET https://api.cm.com/letters/accounts/{accountId}/callbacks/{callbackId}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 https://api.cm.com/letters/accounts/{accountId}/callbacks/{callbackId}