Sign in
Data migration

Translate v2 Nylas ID into v3 Provider ID

Use the connected account ID and a resource type, with an optional list of specific Nylas IDs, to get a response that contains a list of of Nylas IDs and their v3 Provider ID equivalents. Use this API as a one-time operation to translate v2 IDs into v3 Provider IDs. Do not use this API in your code logic as it very data intensive.

To use this endpoint, your v2 Nylas application needs to be linked to the equivalent v3 Nylas application. This endpoint does not work for objects in v2 accounts that have the provider set to Outlook.

By default, the API returns up to 3000 records for the requested resource type related to the v2 connected account, sorted by created_at date. If you specify a list of v2 Nylas IDs, the API returns the v3 Provider IDs for those specific IDs only.

Results are paginated, with a page size of 3000 results. If the response includes a next_page_number field, you can use that number in a request to get the next set of results.

Also, there is a possibility to search results created only after certain Unix timestamp, in Nylas v2 database. To use this, add to body payload start_from_timestamp valid Unix timestamp.

The API is rate limited to 20 requests per second per Nylas application ID.

IMAP folder resource ID

When you make a Translate ID request for an IMAP folder (resource_type: folders), Nylas returns its name in the v3_resource_id field. To get the resource ID for a specific folder, Base64 encode the folder name using the following format: v0:<NYLAS_GRANT_ID>:<FOLDER_NAME>.

post/v3/migration-tools/translate

Request body

resource_type'messages' | 'drafts' | 'threads' | 'contacts' | 'contactgroups' | 'events' | 'calendars' | 'folders' required

The resourece(s) to get translations for.

v2_account_idstring required

The v2 connected account ID to get translations for.

nylas_idsstring[]

(Optional) The list of v2 IDs to translate. If omitted, Nylas returns up to 3000 IDs for the requested resource types related to that v2 connected account. Results are returned sorted by creation date, ascending.

start_from_timestampinteger

(Optional) The Unix timestamp to search for results created after that timestamp.

next_page_numberinteger

(Optional) The page number for the next set of results. This appears in the response only if there are more results available.

Example request

{
  "resource_type": "messages",
  "v2_account_id": "1kb392012l0mr39hmla2exnxu",
  "nylas_ids": [
    "4ro91k0t3ofvzs3b3lij6iqa2",
    "5ro92l1t4pfwzt4c4mijk7jb3",
    "6ro93m2u5qgxzu5d5nijl8kc4"
  ],
  "start_from_timestamp": 1727172308,
  "next_page_number": 2
}

Response

Returns a JSON list of translated objects, with mapped v2 and translated v3 ids.

request_idstring

The request ID.

Example response

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "v2_application_id": "defg12342l0mr39hmla2eabcd",
    "v2_account_id": "1kb392012l0mr39hmla2exnxu",
    "resource_type": "message",
    "translations": [
      {
        "v2_resource_id": "1kb392012l0mr39hmla2exnxu",
        "v3_resource_id": "175ade7f22b0a2f4"
      }
    ],
    "next_page_number": 2
  }
}

Changes