Search

API v2 <> API v3 Migration FAQ

Were you sent here from an error message?  Here's your answer:

Why are the EWS or Office365 accounts having errors when migrating? Or why are there new Invalid grants after migration?

For many Office365 v2 accounts, we are switching from using Exchange Web Services to Microsoft Graph in our v3 API. This may require a new authentication token from Microsoft, so we will need the users to re-authenticate.  This will throw an error during migration because we can't keep using the old token, but that is normal.

Simply have the users re-authenticate in v3 to complete the migration process. We can't bypass this requirement. You may not see this if you were using our Graph calendar beta in our API v2

 

When we migrate over to v3, do we lose access to v2?

No, you will not lose access to your v2 applications/accounts. The migration tool / API simply clones the supported accounts to API v3, leaving API v2 data untouched.

Will my Google Cloud Project and Microsoft Azure settings be transferred over to v3?

You can use the /v3/migration-tools/import-v2-app endpoint (link here) to transfer v2 app settings to the v3 application. Please note, due to limitations from Microsoft, we recommend creating a new Azure application for v3 (Create an Azure auth app for Nylas v3 Guide). This means that the IMAP, iCloud, and Google accounts will be migrated seamlessly, but the Microsoft users will need to re-authenticate.

Are webhooks on API v3 the same as API v2?

No, webhooks have been reworked. You will need to update your business logic to ensure you gather the necessary data from v3 webhooks. You can learn more about this here: V3 Webhook Changes

If I have accounts on both v2 and v3, will I be charged for both accounts for billing purposes?

No, we have logic to de-duplicate and ensure you are only charged per unique account. This is to ensure you can have v2 and v3 running in parallel while you are undergoing the migration process and ensure your production environment remains unaffected and stable while you test the v3 changes. You can learn more about this here: Calculating usage for v3

How can I confirm that my v3 organization is properly linked to my v2 organization?

A quick and easy way to identify this is to see if your v2 applications appear on your v3 dashboard, labeled as `legacy`. If you do not see your `legacy` application, please contact support@nylas.com

How can I find out what accounts are supported using the migration tools?

All Google, iCloud, and IMAP accounts are supported. We have an in-depth chart in the support article below that easily helps you identify supported accounts for the migration process, accounts that will need to re-authenticate, and accounts that are no longer supported (EAS).

Support Article: Migrating accounts from V2 to V3

If my v2 application lives in a different datacenter (EU or US) than my v3 application, can I still use the migration tool?

No, both the v2 application and v3 application must reside in the same datacenter. You cannot change the region if you wish to use the migration tool. An alternative is to create a fresh v3 application and re-authenticate all accounts on the preferred datacenter.

I've received the following error when trying to link v2 and v3 applications, how can I fix it?

Failed to link V2 and V3 applications with message

The error above pertains to the following endpoint: Link a v2 app to a v3 app

Please review Failed to link V2 and V3 applications support article to resolve this issue. If it persists, please contact support@nylas.com.

Is metadata supported for messages on API v3?

Currently, it is not supported. Our team is looking into adding this feature in the future. Please keep an eye out for our Product release notes.

Is there a way to migrate metadata from v2 objects to v3 objects, because the v2 metadata is not returned when making API v3 calls?

No, this is not possible. Metadata for messages will be supported in the future.

What mechanism will be in place for us to map the new grant IDs to our existing user records (account_ IDs?

Our migration API will return the API v3 grant ID generated for an API v2 account ID. See Nylas v2 to v3 Migration tools - Migrate a single v2 Account into v3 Grant

Is the billing_state field still relevant in v3? 

Nylas v3 does not have explicit sync states, so an account's billing status changes only when a grant is created or deleted. Grants continue to be billable as long as they exist, including if they are in an invalid state. How Nylas Calculates Usage

Do I have to re-do Google OAuth verification or Microsoft verification?

In most cases, you should not have to re-do verification with Google or Microsoft. 

There are a few potential exceptions, some of which include:

  • If you are adding new features, there is a large chance you will need to reverify
  • If you are using thread.reply you will need email.read scopes in v3 as opposed to email.metadata in v2. Any time a scope is changed in GCP, you will likely need to undergo verification again.
  • If you authenticate with contacts, you also may need to change scopes if you want to leverage domain or inbox contacts. For use cases that only leverage address book contacts, no mandatory scope changes are expected.

In the case of Microsoft, we are migrating from EAS/EWS to graph. As a result, you’ll need to create a new Azure project, though this process is generally much more seamless and not interruptive relative to Google’s equivalent. 

 

 

 

Links for commonly recommended migration docs

 

Updated

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.