Version:
Only show these results:

Migrate application data from v2.x to v3

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 cannot 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 could not be migrated and the error Nylas encountered.

Many Microsoft accounts cannot 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

After you start the migration, go to your v3 application, and check the list of migrated connectors to make sure it looks complete.

At minimum, you need to add the v3 Nylas redirect URIs to the allowed URIs for your provider auth apps, and update the new connectors for each provider to make sure they have the correct scopes.

  • 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, update your provider auth app 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.

Update the imported connectors

The migration tool creates v3 connectors that are equivalent to the application's v2 integrations. However, Nylas can't configure these for you. After you start the migration, check each migrated connector and update it if any fields are missing or blank. (Connectors for IMAP and iCloud do not have any settings to configure.)

For each connector, add or update the client_id and client_secret for the associated provider auth app as needed.

In v3, Nylas no longer uses "Nylas scopes", but directly uses the provider scopes instead. The migration tool creates connectors on the new v3 application, but can't pick the scopes for you.

Make a list of the v2 API endpoints your project uses, then read the v3 scopes documentation to determine the scopes for the equivalent v3 APIs. When you know what v3 scopes you need, add them to your provider auth apps, and make sure the connectors in your application reflect the correct scopes.

Add v3 authorized redirect URIs to provider auth apps

The authorized redirect URIs for Hosted Auth changed in v3, so you must update all provider auth apps that you want to connect to Nylas v3. Add one, or both, of the following 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 cannot 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.

Cut over to v3

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 just created. Invalidate or remove the old v2 connected accounts for clarity. Nylas deduplicates v2 and v3 accounts for billing purposes, but deleting the v2 account can help you keep track of which users have migrated to the v3 system.

Testing and tuning

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.