Migrating accounts from V2 to V3

This article outlines the two methods available for migrating accounts from V2 to V3, utilizing the object V2 to V3 translation tool. It also details the benefits and disadvantages of each method.

Note: Running accounts in both V2 and V3 on a single app will not result in double billing but may increase workload and the likelihood of encountering rate limiting.

Important: We recommend turning off the V2 account at the earliest opportunity, we have seen instances where IMAP providers do not appreciate two sync engines connected to the same grant.


Prerequisites


Migration Methods

1. Gradual Migration

Steps:

  1. Change the Auth URL on your application to point to the V3 application.
  2. Over time, revoke tokens to force customers to authenticate on your new application.

Benefits:

  • Migrate at your own pace.
  • Same method for all accounts.

Disadvantages:

  • All customers will need to re-authenticate.
  • Can not migrate scheduler Slugs

2. Nylas Account Migration Tool

Availability: The tool is available via the API, it will be added to the dashboard in due course. 

Benefits:

  • No disruption for GMAIL, IMAP, and MS Graph (few accounts) accounts.
  • Clones the accounts, allowing them to run in both V2 and V3.
  • Required to migrate scheduler slugs

Disadvantages:

  • Only Microsoft accounts will need to re-authenticate, as you need to create a new app.
  • Requires development to switch from V2 to V3 webhooks when the grant is online.

 

#

v2 Provider Type

v3 Equivalent

Automatic migration support by migration tool

Extra steps

End user (owner of the email) has to reauth

Notes

kisspng-google-logo-5b02bbe1d5c6e0.2384399715269058258756.jpg

Provider:Google

Auth: OAuth (hosted/native)

Provider: Google

Auth: OAuth (hosted/custom)

YES

 

No

 

kisspng-google-logo-5b02bbe1d5c6e0.2384399715269058258756.jpg

Provider: Google

Auth: Service Account

Provider: Google

Auth: Bulk Auth

YES

 

No

 

microsoft-365-2022-logo-7B23759A49-seeklogo.com (1).png

Provider: Microsoft Graph

Auth: OAuth

Provider: Microsoft Graph

Auth: OAuth (hosted/custom)

YES

 

No

 

microsoft-365-2022-logo-7B23759A49-seeklogo.com (1).png

Provider: Outlook / Live

Variation: Personal

Auth: Basic (username/password)

Provider: Microsoft Graph

Auth: OAuth

No

Basic to Oauth, different object type.

Yes

eg domains: live.com, hotmail.com, …

microsoft-365-2022-logo-7B23759A49-seeklogo.com (1).png

Provider: Microsoft O365

Variation: non-personal, not-on-prem

Auth: OAuth Modern

Provider: Microsoft Graph

Auth: OAuth

Grants get created with invalid state

New Azure application.

End user reauths again.

Yes

 

             

microsoft-365-2022-logo-7B23759A49-seeklogo.com (1).png

Provider: Exchange O365

Variation: non-personal, not-on-prem

Auth: ServiceAccount (Basic)

N/A

N/A

N/A

N/A

Deprecated by Microsoft in 2022.

microsoft-365-2022-logo-7B23759A49-seeklogo.com (1).png

Provider: Exchange O365

Variation: non-personal, not-on-prem

Auth: ServiceAccount (OAuth refresh_token)

Provider: Microsoft Graph

Auth: Bulk Auth

No

New Azure application.

No

domains:

9

Provider: Exchange On-Prem

Variation: non-personal, on-prem

Auth: Basic (username/password)

Provider: Exchange (v3)

Auth: Basic also

Yes (WIP :warning: )

 

No

We also support syncing with IMAP if the use case is email only but that requires extra configuration in the server.

             

11

Provider: Exchange On-Prem Hybrid

Variation: non-personal, on-prem, hybrid

Auth: ServiceAccount (OAuth refresh_token)

Provider: Microsoft Graph

Auth: Bulk Auth

No

New Azure application.

No

Nylas cannot distinguish between on-prem and not on-prem, therefore it treats these accounts similar as #8

12

Provider: Exchange On-Prem

Variation: non-personal, on-prem

Auth: ServiceAccount (Basic)

N/A

N/A

N/A

N/A

Microsoft has shutdown and deprecated most of the capability already.

We will not support it.

13

Provider: IMAP

Auth: Basic (username/password)

Provider: IMAP

Auth: Basic (username/password)

Yes

 

No

Password can be “App Password”.

14

Provider: iCloud

Auth: Basic (username/password)

Provider: iCloud

Auth: Basic (username/password)

Yes

 

No

Password SHOULD be “App Password”.

This connector syncs both Email (IMAP) and Calendar (CalDav protcol) under the same grant.

15

Provider: Virtual Calendar

Auth: N/A

Provider: Virtual Calendar

Auth: N/A

Yes (WIP :warning: )

 

N/A

Migration of data still WIP

 

FAQ:

How do I handle the switchover from V2 to V3? The concern is lost synced objects between moving from V2 to V3.

  1. If using the Gradual method or the accounts are Microsoft you will need to record the time you hit /revoke on the V2 application and when the customer re-authenticates. For this time gap you will need to GET /object_endpoint for all the objects in question. 
  2. If using the migration tool then the accounts can work in parallel and you programmatically switch between API's.

 

Resources

V3 migration considerations

How do I migrate my V2 organization, applications, accounts and objects to V3

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.