Motivation

A new version of the „Mail Communication Tracking Push API“ is planned that will contain changes compared to the previous version. This new version 1.2 is expected to be available in April.

Details of the upcoming changes are described below.

 

Change of webservice URLs

The URLs of the web services have changed, see the following table.
Mostly only the URL changes: "/subscription/" became„/subscriptions/“.

New Webservice

Description

Old Webservice

GET /certificates/default

Gets the certificate chain of the push service (X.509).

GET /cert.pem

GET /subscriptions

Accesses all push subscriptions for the logged-in user

GET /subscription

POST /subscriptions

Create push subscription with settings

POST /subscription

GET /subscriptions/{id}

Gets a push subscription by its id

GET /subscription/{id}

PUT /subscriptions/{id}

Update push subscription by UUID

PUT /subscription/{id}

DELETE /subscriptions/{id}

Deletes a subscription

DELETE /subscription/{id}

POST /subscriptions/{subscriptionID}/confirmation

Confirms the validity of the subscription

GET /verify/{id}

POST /subscriptions/{subscriptionID}/replay

Requests events to be replayed

GET /repush/{id}/{day}

 

Data Structure for Subscription

Within the JSON data structure for subscriptions, field names have changed

  • exportEndpoint becomes dataCallbackURL
  • documentAmount becomes numberOfRecords

 

Also, an additional field "validationCallbackURL" has been added.
This allows a separate callback URL to be specified for subscription validation.
Previously, the same callback URL was used for validation as for data delivery.

Use the callback URL for data delivery at this point if you use this callback URL already for validations

Provide the callback URL for data delivery if this callback URL is already used for validations

 

Changed values for export format

The possible values for the "ExportFormat" field have been changed to the corresponding content types

Instead of                   "json"                   now     "application/json"

Instead of                   "xml"                    now     "application/xml"

 

Change when saving subscriptions

When creating or modifying subscriptions via

   POST /subscriptions

   PUT /subscriptions/{id}

in case of success (status 200)

  • instead of the status object sent in the response body (code, message, timestamp)
  • now an object with the input data is returned.

When creating new subscriptions, in addition the generated ID of the subscription is returned.

 

 

 

Change when validating subscriptions

The one-time validation for newly created subscriptions changes.

With the upcoming release, a separate callback URL for validation can be specified in the subscription (see above)

 

For validation, this callback URL is called with a modified record:

  • the attribute name of the URL to be called changes from "validationUrl" to "confirmationURL".
  • the field "pushSubscriptionId" is omitted, it is included in the "confirmationURL", and is also supplied when creating subscriptions.
  • a field "signature" is added, which is used as additional security measure

 

Call the web service provided in the "confirmationURL" for confirmation. This is the call of

POST /subscriptions/{subscriptionID}/confirmation

 

Compared to the previous confirmation the HTTP method changes from GET to POST.

As POST parameter the content of the field "signature" must be supplied (from the callback URL)

 

 

Change when reading subscriptions

If individual or all existing subscriptions are read via

GET /subscriptions

GET /subscriptions/{id}

only the data of the subscription(s) will be delivered as response.

Previously, this data was encapsulated in an object that also contained status information.
This status information and the encapsulating object are omitted.

 

 

Change when replaying PUSH messages

To resend PUSH messages, the web service

   POST /subscriptions/{subscriptionID}/replay

can be used

 

The HTTP method has changed from GET to POST. The requested replay date must be supplied as POST parameter.

 

 

Omission of the sandbox web service

The web service

  POST /sandbox/generate/{id}

which was previously only available in the sandbox environment for generating test PUSHs in the development environment is no longer available.

To generate test PUSHs you can use the replay web service

 

Change of http status code on successful calls

For some web services, a different status code is sent instead of http status 200 on a successful call

 

Status 202 „Accepted“

The following web service is processed asynchronously, therefore HTTP status 202 is returned in case of success

  • POST /subscriptions/{subscriptionID}/replay

 

Status 204 „No Content“

For the following web services no data is provided in the response.
Therefore, the more appropriate HTTP status 204 is used instead of 200

  • POST /subscriptions/{subscriptionID}/confirmation
  • DELETE /subscriptions/{id}

 

Change of error handling

There are two changes in error handling that affect all web services

The possible 4xx error codes have changed

  • some web services may return different error codes than before
  • a new error code 403 "Forbidden" can be returned.
  • error codes 406 and 422 are omitted and are no longer returned

 

The error status data object returned in the event of an error (status 4xx) has a different structure.
Instead of code, message, timestamp now the attributes title, statusCode, detail, instance are returned