Main differences between V1 and V2

OAuth2

The new API uses OAuth2 which brings a smoother experience for users of 3rd party integrations, at the expense of a little bit more coding for developers.

Our Transition service will help you exchange valid Mailbox API 1.0 API keys for renewable OAuth2 tokens.

Strict meaning of the HTTP verbs

POST and PUT will always overwrite whole resource (entity) in V2, while V1 was not consistent in this approach. For example, when you call the Update Customer and omit some fields, these fields will treated as being set to null. The API uses PATCH for partial updates - have a look at the Update Conversation endpoint, as some sub-resources can be manipulated directly.

Sub-resources

You can read and update some sub-resources directly, see Delete Email or Update Tags endpoints for examples.

Error messages and Correlation ID

We reworked the error messages to be more descriptive and link to documentation if possible. Every request also contains a Correlation-ID response header, which is unique for each request. You can see the value of this header in the logref field of the error response. If you run into an error or unexplained action on the API, including the Correlation-ID in any support requests allows us to track down your specific call immediately.

Every response (with the exception of Reports) contains a _link section with a list of links that allow you to load related entities as and when needed.