Migrating to Mailbox API 2.0
Mailbox API 2.0 is officially available for use. This guide covers all that you need to know about the new API and how to transition any existing integrations from our legacy API to Mailbox API 2.0.
In this article
What is Mailbox API 2.0?
Mailbox API 2.0 is the second generation of our API. While the upgrade to OAuth 2.0 was a major focus for this version, we’ve also added a few other improvements to help make the API easier to navigate. To get you started with Mailbox API 2.0, here are a few highlights of the changes:
- We added user-friendly authentication for third party integrations.
- The documentation includes a breakdown of the main differences between V1 and V2.
- We doubled our rate limits.
- If a request fails, we’ll tell you why!
Sunsetting Mailbox API 1.0
With Mailbox API 2.0 now publicly available for use, we’ll be officially shutting down all support for Mailbox API 1.0 (formerly known as Help Desk API) on June 6th, 2019. If you have any custom or third party integrations using the legacy API, they will need to be updated to the new API.
While your update to Mailbox API 2.0 is in progress, it’s important to note that Mailbox API 1.0 will continued to be supported in a maintenance capacity. To help us prepare for 1.0’s retirement, we’ll restrict the creation of legacy API keys on May 6th - Users won’t be able to generate fresh API keys after that point.
When we shut down support for the API on June 6th, we plan to:
- Freeze the legacy API code. Even if the API breaks, our team has no plans of deploying any further fixes or updates
- Remove Mailbox API 1.0 documentation from our developer docs
- Our support team will no longer be able to lend a hand with legacy Mailbox API 1.0 questions
To ensure that existing integrations are compatible with Mailbox API 2.0 and that they continue to function after June 6th, all integrations must be transitioned off of legacy API 1.0.
What’s staying the same?
Our Docs API, Webhooks, and Custom Static and Dynamic apps all use different systems behind the scenes, meaning there won’t be any changes made to these features as a result of the Mailbox API 1.0 sunset.
Updating your integration to Mailbox API 2.0
If you’ve built an integration using our Mailbox API 1.0, now’s the time to start updating your apps so you don’t experience any interruptions down the road. At a high level, your migration plan will need to tackle two things:
- Update all API calls to use the new Mailbox 2.0 endpoints.
- Update your integration’s authentication method to use OAuth 2.0.
Bonus points: If you've developed a third party integration using the legacy API and would like to migrate users to the new API automatically behind the scenes, we built a handy transition tool just for you.
If you have any questions or concerns about moving to Mailbox API 2.0, please don’t hesitate to reach out. We’re here to help with anything we can during this transition period!