Sign in
App migration

Batch clone v2 accounts to v3 grants

Starts a batch migration job to clone v2 connected accounts to v3 grants.

Before you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3 applications and you need to have a working equivalent authentication connector for each provider you use. If you need help with this process, learn how to get support.

When you make a batch clone request, Nylas starts two background jobs:

  • A snapshot job that prepares non-sensitive v2 account data for migration.
  • A batch clone job that migrates the v2 account data to v3 grants.

Nylas handles all data and logic for these jobs and runs them in the background to they don't block API responses.

You can filter for certain types of accounts by specifying properties in the body of your request. Use these options when you want to try migrating certain types of accounts in smaller batches, or to retry failed migrations. If you don't specify any filters, Nylas uses the default values.

During migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's v2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted and securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas network.

This endpoint is rate limited to 20 requests per second, per Nylas application ID.

Create placeholder grants

Nylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token authentication. It can't fully migrate some types of Microsoft accounts because of provider limitations and scope changes in v3.

By default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't automatically migrate. These grants act as "placeholders" that the user can manually authenticate to later. You can turn this feature off for Microsoft accounts only by setting the clone_exchange query parameter to false, or for all providers by setting allow_invalid_grant_creation to false.

post/v3/migration-tools/snapshot-batch-clone

Query parameters

allow_invalid_grant_creationboolean

(Not supported for Microsoft) When true, Nylas creates invalid v3 grants with fake credentials for all connected accounts in your request. These grants act as placeholders that users can authenticate to later.

clone_exchangeboolean

(Microsoft only) When true, Nylas creates invalid v3 grants with fake credentials for any Microsoft accounts that can't be automatically migrated. These grants act as placeholders that users can authenticate to later.

Request body

limitinteger

Number of accounts to migrate. Nylas orders the migration records created by the snapshot job, by imported_at timestamp from oldest to newest.

offsetinteger

Number of accounts to skip. Nylas orders the migration records created by the snapshot job, by imported_at timestamp from oldest to newest.

providersstring[]

Use this setting to limit the migration job to a specific provider or providers, so you can migrate one type at a time.

mode'all' | 'only_new' | 'only_failed'

Use this setting to limit the migration job to accounts that have specific statuses, or when retrying failed migrations. - 'all': No filtering, migrate all accounts that meet the request criteria. - 'only_new': Migrate only accounts that haven't attempted migration. - 'only_failed': Migrate only accounts that attempted migration previously and were marked as failed.

Example request

{
  "limit": 10,
  "providers": [
    "google",
    "microsoft"
  ],
  "mode": "all"
}

Response

Immediately returns a list of the two jobs for the migration run:, snapshot and batch clone. Those jobs continue to synchronously run in the background.

request_idstring

The request ID.

Example response

{
  "request_id": "5967ca40-a2d8-4ee0-a0e0-6f18ace39a90",
  "data": {
    "clone_job": {
      "job_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
      "type": "snapshot",
      "public_application_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
      "status": "pending",
      "count_all": 20,
      "count_success": 10,
      "count_failed": 5,
      "count_warning": 5,
      "created_at": 1617817109,
      "updated_at": 1617817109,
      "linked_job_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
    },
    "snapshot_job": {
      "job_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
      "type": "snapshot",
      "public_application_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47",
      "status": "pending",
      "count_all": 20,
      "count_success": 10,
      "count_failed": 5,
      "count_warning": 5,
      "created_at": 1617817109,
      "updated_at": 1617817109,
      "linked_job_id": "e19f8e1a-eb1c-41c0-b6a6-d2e59daf7f47"
    }
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.