Version:
Only show these results:

Migrate application data from v2.x to v3 using the Migration APIs

The Nylas Migration APIs are designed to help you migrate your application and user data from v2 to v3.

These APIs are for one-time translation for migration purposes only You can retry these APIs if you encounter issues, but they will be rate limited and you should not use them as part of your project's code or object handling logic.

Nylas provides several Migration APIs to help you migrate your v2 Nylas data after you upgrade the rest of your application to use Nylas v3. As a reminder, Nylas v2 will be deprecated on December 31, 2024.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

Prerequisites

Before you begin:

  • Make sure your v2 and v3 organizations are linked. Contact Nylas Support if you don't see all of your legacy v2 applications from both regions in the Dashboard, or if you aren't sure your v2 and v3 accounts are linked correctly.
  • Set up equivalent v3 authentication systems.
    • If your v2 application has users connecting using a Microsoft integration, you should create a new Azure provider auth app so you can use the v3-compatible Graph scopes.
    • If your v2 application has users connecting using Google, make sure your provider auth app is updated with the v3 Nylas redirect URIs.
    • If your v2 application has users connecting using Yahoo, consider creating a Yahoo OAuth application. This greatly improves speed and reliability when connecting to Yahoo accounts.

⚠️ Your v2 and v3 applications must be in the same data center region to use these tools. You can only use these tools to migrate a v2 application to a v3 application in the same region. You cannot use these to move a v2 application to a different region.

Migration process

An automated migration tool is also available in the v3 Dashboard.

To migrate your applications yourself, follow the process described below. If you have trouble, contact Nylas Support for assistance.

⚠️ Make sure you use the correct region! In Nylas v3, you mange applications for both the U.S. and E.U. regions using the same Dashboard. If you're migrating a v2 application to v3, make sure you create the v3 application in the correct region.

  1. Use the Link Applications API to link your v2 application to its equivalent v3 application.
  2. Use the Import app Settings API to migrate your v2 Integrations to v3 Connectors, and copy over other important application settings.
    If you have integrations with Microsoft, the migration to v3 requires all new scopes and you should create a new Azure provider auth app for your v3 Microsoft connector.
  3. If you have a Microsoft integration in v2, create a new provider auth app for Microsoft Azure with the v3-compatible Graph scopes, and use its information to finish setting up your migrated Microsoft connector. See Migrating Microsoft accounts for detailed instructions.
  4. Make sure that any provider auth apps you use with v3 hosted authentication include the Nylas v3 redirect URIs:
    • For U.S. Hosted authentication use https://api.us.nylas.com/v3/connect/callback
    • For E.U. Hosted authentication use https://api.eu.nylas.com/v3/connect/callback
  5. If you haven't already, upgrade your project code to use the Nylas v3 APIs and systems. Nylas recommends you do this before you migrate user accounts.
    Make sure you update your login screen to use v3 authentication, so end users who reauthenticate can seamlessly use v3.
  6. Use the Migrate a single account API to test user account migration, then use the Batch migrate accounts API to migrate your v2 connected accounts to v3 Grants.
    Migrated grants are deduplicated with their v2 versions, so they are counted as one connected account for billing purposes.
  7. Subscribe to v3 notification triggers (either webhooks or Pub/Sub) for your users, so you can keep track of any objects that change while you are transitioning applications.
  8. Test your v3 applications to make sure everything is working as intended. You can re-migrate user accounts if needed.
  9. Have your users re-authenticate using v3 (or use bulk authentication if available) to start using the v3 grants you just created. Invalidate or remove the old v2 connected accounts.