Version:
Only show these results:

Migrate application data from v2.x to v3 from the v3 Dashboard

The Nylas v3 Dashboard offers a migration tool that automatically creates a new v3 Nylas application for you, and transforms and copies over your settings and user data.

If you prefer a more self-directed approach, Nylas provides several Migration APIs to help you migrate your v2 Nylas data.

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

Dashboard migration tool limitations

  • You can only import a v2 application into a v3 application in the same data center region. You can't use the Import tools to move a v2 application to a different region.
  • The migration tool doesn't migrate webhook settings or subscriptions.
  • The import process creates equivalent connectors, but doesn't set them up for you.
  • The import process doesn't update your provider auth apps.
  • Imported Microsoft accounts (almost always) must reauthenticate because of scopes changes in v3.

Start the migration process

  1. Go to the Nylas v3 Dashboard and log in as an admin user.
    Only administrators can migrate v2 applications.
  2. Find the v2 app you want to migrate. It'll be marked Legacy.
  3. Click Migrate app next to that legacy app to create a new v3 application.
  4. In the dialog, confirm the title and the environment tag (Development, Stating, Production), and optionally add a description.
  5. Click Create app. Nylas copies your v2 connector data to the v3 application and starts migrating connected accounts.
    After you start a migration, Nylas brings you back to the application list. The migration process is asynchronous, and you can continue working on other migration tasks while Nylas works.

The account migration might take some time, so you can continue the steps in this guide while you wait for it to complete.

The v3 version of the application appears in the list with a Migrated label. The info icon shows the v2 application ID that the v3 app is based on. You can click the v3 application and go to the Grants page to see the migration progress.

Review migrated accounts

When Nylas finishes migrating accounts to Grants, the Grants page for the new v3 application shows progress as 100%. You can then download a CSV report of the migration details, including any accounts that couldn't be migrated and the error Nylas encountered.

Many Microsoft accounts can't be migrated in a valid state because Nylas v3 uses Graph scopes. See Migrating Microsoft accounts for more details.

👀 Good to know: The Nylas migration job marks an account migration as failed if it was unable to import and create a valid grant for that account. However, for many of these cases, the user can still start a completely new authentication on the v3 system to use your application. This is expected in the case of Microsoft accounts that used Exchange, such as personal accounts on Hotmail, Live, and Outlook.

Update provider auth apps and connectors

The Dashboard migration tool creates v3 connectors that are equivalent to your project's v2 integrations. However, Nylas can't completely configure each connector for you. You should check the list of migrated connectors to make sure it looks complete, then update the connectors to make sure they have the correct scopes and add the v3 Nylas redirect URIs to the allowed URIs for your provider auth apps.

Depending on your project, you might also need to do the following tasks:

  • If your v2 Nylas 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.

Update imported connectors

After you start the migration process, 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.)

🔍 Nylas v3 no longer uses "Nylas scopes", but uses provider scopes instead. The Dashboard migration tool creates connectors on your new v3 application and, for most providers, translates your v2 Nylas scopes to the equivalent v3 provider scopes. You must configure your Microsoft connector manually because of the transition to Graph scopes.

To verify the scopes you need, make a list of the v2 API endpoints your project uses, and read the v3 scopes documentation to determine the scopes for the equivalent v3 endpoints. If you need to update your scopes, be sure to change them in both your provider auth app and the v3 Dashboard.

Add v3 redirect URIs to provider auth apps

The authorized redirect URIs for Hosted Authentication changed in Nylas v3, so you need to update all provider auth apps that you want to use. Add one, or both, of the following URIs to the Authorized redirect URIs section of each provider auth app:

  • U.S.: https://api.us.nylas.com/v3/connect/callback
  • E.U.: https://api.eu.nylas.com/v3/connect/callback

Pub/Sub requirement for Google Email API

If your users authenticate with Google and you get message webhooks, you must set up a Pub/Sub topic so Google delivers new message notifications in a timely manner.

Reconfigure webhooks

While the Migration tool copies most of your settings and data, it can't re-create your webhook subscriptions. Follow this general process to upgrade your v2 webhook implementation to v3:

  1. On your v2 app, make a v2 GET /a/<NYLAS_CLIENT_ID>/webhooks request to get a list of your existing webhook subscriptions.
  2. Set up a v3 environment as in the guide above, and make sure your auth systems include any new scopes for v3 webhook triggers you plan to test.
  3. Create a grant to test your webhook subscriptions.
  4. Set up a webhook URL to receive test data.
  5. Make a v3 POST /v3/webhooks request to set up your webhook destination, and include the triggers you want to subscribe to.
  6. Test some actions and observe incoming data. You can use the new Send test event API to generate webhook messages.

When your tests meet your requirements, upgrade any code that handles v2 webhooks.

Upgrade your project code

Upgrade your project code as described in the rest of the v3 Upgrade guide.
Make sure you update your login screen to use v3 authentication, so end users who reauthenticate can seamlessly use v3.

Testing and tuning

If you're already done with the rest of your migration, have a ☕️ and maybe even some 🍰 to celebrate! You're almost done.

Have your users re-authenticate using v3 (or use bulk authentication if available) to start using the v3 grants you created. Nylas de-duplicates v2 and v3 accounts for billing purposes, so don't delete the old v2 grants just yet.

Service providers like Google and Microsoft implement strict rate limiting. Because Nylas v3 queries providers directly, it's important that your API requests limit the amount of data they request so you don't hit these provider rate limits.

Once your v3 implementation is stable, you can start downgrading and removing your v2 accounts so you can track which users have migrated to the v3 system. After you test your v3 implementation for a couple of days and you're happy with the migration results, reach out to your Nylas representative or contact Nylas Support to delete your v2 instance.