Version:
Only show these results:

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

⚠️ The Migration API is designed for one-time translation for migration purposes only. You can retry your requests if you encounter issues, but they'll be rate limited. You should not use these endpoints as part of your project's code or object handling logic.

The Nylas Migration API helps you migrate application and user data from Nylas v2 to v3 after you upgrade the rest of your application. 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!

Nylas also offers an automated migration tool in the v3 Dashboard.

Prepare for migration

  • Make sure that your v2 and v3 organizations are linked. Contact Nylas Support if you don't see all your legacy v2 applications from both regions in the v3 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 auth app so you can use the v3-compatible Microsoft Graph scopes.
    • If your v2 application has users connecting using Yahoo, consider creating a Yahoo OAuth app. This greatly improves speed and reliability when connecting to Yahoo accounts.

Migrate your project to Nylas v3

⚠️ Your v2 and v3 Nylas applications must be in the same data center region to use these tools. You can't use the Migration API to move a v2 application to a v3 application in a different region.

To migrate your applications using the Migration API, follow the steps below. If you have trouble, contact Nylas Support for help.

  1. Use the Link Applications endpoint to link your v2 Nylas application to its equivalent v3 application.
  2. Use the Import App Settings endpoint to migrate your v2 integrations to v3 connectors, and copy other important application settings.
  3. Check each migrated connector and update the client_id, client_secret, and any fields that are missing or blank, as necessary. (IMAP and iCloud connectors don't have any settings to configure.)
  4. If you have a Microsoft integration in v2, create a new Azure auth app with the v3-compatible Microsoft Graph scopes and use its information to finish setting up your migrated Microsoft connector. See Migrating Microsoft accounts for detailed instructions.
  5. Make sure that any provider auth apps you plan to use with v3 Hosted Authentication include the v3 Nylas redirect URIs:
    • U.S.: https://api.us.nylas.com/v3/connect/callback
    • E.U.: https://api.eu.nylas.com/v3/connect/callback
  6. If you haven't already, migrate your project code to use the v3 Nylas APIs and systems. Nylas recommends you do this before you migrate your user accounts.
    Make sure you update your login page to use v3 authentication, so users who re-authenticate can seamlessly use Nylas v3.
  7. Use the Migrate a Single Account endpoint to test user account migration, then use the Batch Migrate Accounts endpoint to migrate your v2 connected accounts to v3 grants.
    Nylas automatically de-duplicates migrated grants from their v2 counterparts, so they're counted as one account for billing purposes.
  8. Subscribe to v3 notification triggers (either webhooks or Pub/Sub) so you can keep track of any objects that change while you're transitioning to your v3 application.
  9. Test your v3 applications to make sure everything is working as intended. You can re-migrate user accounts if needed.
  10. Have your users re-authenticate using v3 (or use bulk authentication, if available) to start using the v3 grants you created.

When you're confident that the migration was successful, test your v3 implementation for a couple of days. When you're happy with the results you can downgrade and invalidate or remove the old v2 connected accounts. When you're fully on v3 contact your Nylas representative or contact Nylas Support to delete your v2 instance.