Object ID translation from 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.

Note: V2 ID's can continue to be used in V3 GET and DELETE endpoints for up to a year after the EOL in October 2024.

Migration Support

We currently support the following resource_type:

  • messages
  • threads
  • calendars
  • events
  • drafts
  • folders
  • contacts


  • 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.


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


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)

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 '{

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.

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


"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


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



Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.