Legacy Mailbox API 1.0 and Mailbox API 2.0

With the launch of Mailbox API 2.0, our public API received a number of hearty updates aimed at improving performance and creating a better experience for both developers and integration users. This article covers the primary differences between the two APIs, which are helpful to known as you plan to migrate any existing integrations from our legacy API to Mailbox API 2.0.

OAuth 2.0 Authentication

We’ve upgraded Mailbox API 2.0 to use OAuth2 which provides a smoother, more secure experience for both developers and users of third party integrations.

Legacy Mailbox API 1.0 will be retired on June 6th, 2019 If you’ve built an integration using our legacy Mailbox API 1.0, now’s the time to start updating your apps so you don’t experience any interruptions when this version is turned off on June 6th, 2019. To help make the transition a bit easier, we’ve created a transition service that will allow developers of third party integrations to exchange valid Mailbox API 1.0 API keys for renewable OAuth 2.0 tokens.

Strict meaning of the HTTP verbs

POST and PUT will always overwrite whole resource (entity) in 2.0, while 1.0 was not consistent with this approach. For example, if you call the Update Customer endpoint and omit any fields, these fields will treated as being set to null and will be cleared.

For partial updates, Mailbox API 2.0 uses PATCH. Using the Update Conversation endpoint as an example, you’ll find that some sub-resources for specific conversations can be manipulated directly.

Update sub-resources directly

With Mailbox API 2.0, you can read and update some sub-resources directly. The Delete Email and Update Tags endpoints are great examples of this new behavior.

Improved error messages and Correlation ID

We’ve also reworked the error messages provided in 2.0 to be more descriptive and link to documentation whenever possible. Every request also contains a Correlation-ID response header, which is unique for each request and can be found 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 conversations 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.

Increased rate limits

We’ve also given rate limits a nice increase - you’ll now have 400 requests per minute, up from 200 requests in the legacy API. Write requests (POST, PUT, DELETE, and PATCH) will count as 2 requests.