How to handle Object ID translation from API V2 to V3

Nylas v3 API offers an endpoint to migrate existing v2 object IDs into v3 object IDs. This document covers the endpoint and other details you should be aware of while migrating data.

Which accounts can have their objects translated?

The only accounts we can not translate:

• Password authenticate Microsoft accounts (except for Microsoft Exchange on-premise on EWS)
• Token or Password authenticated accounts with only Active Sync (EAS) access

Please contact support if you wish to identify these accounts ahead of time, please use the Support Bot in the bottom right of your screen, to automate this process.

Translate ID: feature coverage:

Prerequisites

If you are migrating data to your production v3 application, we advise you to first test this functionality within your staging environment.

• Staging Migration:

  • v2_staging_application => v3_staging_application

• v3 Application:

  • API_KEY
  • Connectors (optional)
  • For normal accounts, we recommend using the same Google credentials for the connector as you have in your v2 application, except for accounts connected via a service account.

• v2 Application:

  • Additional scripts for data migration (optional)

Migration Options

We have some tools to allow you to translate objects from V2 to V3

1. Mass object translation (see below)
2. Use V2 object in V3 endpoints (will be released end of July)

Mass object translation tool

We currently support the following resource_type:

• messages
• threads
• calendars
• events
• drafts
• folders
• contacts (Except for EAS, Active Sync, accounts)

Note:

• We are unable to migrate any EAS accounts to v3 object IDs.
• Microsoft accounts connected as EAS won’t be able to use the Microsoft Graph API.
• To get a list of EAS accounts please contact support

Limits:

• Max per page = 3000
• 58000 IDs with various accounts & providers & resource_types it took 50~53 seconds

Steps for Migration

Link Your v2 Application to Your v3 Application:

curl --location --request PATCH 'https://api.[us or eu].nylas.com/v3/applications'  \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API_KEY}}' \
--data '{
"v2_application_id":"bna2kc0o90naihvn5x6lkwmaa"
}'

Call the Endpoint to Retrieve v3 Object IDs:

Please note that the accounts don’t have to migrate before using this endpoint. This allows you to enrich the data before transitioning to v3.

Note: If you do not include nylas_ids then we will return 3000 objects which you can paginate through.

curl --location 'https://api.[us or eu].nylas.com/v3/migration-tools/translate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API_KEY}}' \
--data '{
"resource_type": "messages",
"v2_account_id": "dr4uq5akc2rnyxavg2s09y4vd", // V2 ACCOUNT_ID
"nylas_ids": [
// MAX NUMBER OF IDs = 3000 // OPTIONAL
]
}'

Response:

{
"request_id": "2a200f3c-b544-471c-9053-dbc4e51734bb",
"data": {
"v2_application_id": "2rtcijlk35kim179x7fkru7fg",
"resource_type": "messages",
"v2_account_id": "dr4uq5akc2rnyxavg2s09y4vd",
"translations": [
{
"v2_resource_id": "ebofsm3ak1arhtjf9owoxw7kn",
"v3_resource_id": "1746042846480030544"
},
{
"v2_resource_id": "41o50d2tzunsfk0yuouma6u8s",
"v3_resource_id": "1746418981305066631"
},
{
"v2_resource_id": "b2tglw1rbb6vmbisx7ar4p1nf",
"v3_resource_id": "1746419133928955146"
}
// ...more translations
]
}
}

References:

Issues and Differences During Migration from V2 to V3

Migrating accounts from V2 to V3

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

Updated August 28, 2024 13:22