Mailbox API 2.0 and Legacy API 1.0
After ending support for the legacy API on June 6, 2019, Mailbox API 1.0 will be deprecated on November 20, 2019. If you have existing integrations running on the legacy API, this guide covers all that you need to know about moving to our new Mailbox API 2.0 before the final deadline.
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 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!
Check out the Mailbox API 2.0 changelog to get the full scoop on what our API team has been up to!
Do I have a legacy API key?
To check if you have a legacy, Mailbox API 1.0 key, head over to your User Profile > Authentication > API Keys. From there, you can review which API keys might still be used by custom or third-party integrations and revoke access to any keys that are no longer in use.
If your API key is still in use, do not revoke access until you have fully migrated to Mailbox API 2.0. If you revoke access before you've transitioned to the new API, your integration service will be disrupted.
Mailbox API 1.0 will be shut down
To ensure that your account doesn't run into any service disruptions, please make sure your account is using Mailbox API 2.0 by November 20, 2019. After that date, we plan to fully disable the legacy API and remove it from Help Scout. That means:
- API access for existing legacy keys will be revoked and all legacy API keys will be removed from Help Scout
- Any integrations still running on the unsupported API will no longer function. This includes both custom-built and third-party integrations
- The transition service will be disabled
- Our support team is not able to lend a hand with legacy Mailbox API 1.0 questions
If you have any custom or third party integrations still using the legacy API, they will need to be updated to use the new API. While your existing 1.0 integration may continue to work through November 20, it will not function beyond that date.
Third-Party Integrations: In Progress
Our friends at Fivetran and Segment are busy working through their Mailbox API 2.0 migrations as we speak. Not to worry, these integrations will continue to function as our partners work to update and launch their code.
Third-Party Integrations: Deprecated
After keeping in contact with our third-party partners to communicate our timelines, we're afraid that the AgileCRM and Clickdesk integrations remain on the unsupported legacy API and will stop working on November 20, 2019. To submit an update request for either of these integrations, please contact the AgileCRM and ClickDesk teams directly.
What stayed the same?
Our Docs API, Webhooks, and Custom Static and Dynamic apps all use different systems behind the scenes. There were no changes made to these features as a result of the Mailbox API 1.0 sunset.
Update to Mailbox API 2.0
If you’ve built an integration using the legacy API, it will need to be updated to Mailbox API 2.0. At a high level, your migration plan should 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. Our team is here to help make the final transition as smooth as possible.