Change data residency region
📝 This page discusses both Nylas v2.x and v3. For more information about the newest version, see the Nylas v3 documentation.
This page describes how to change the data residency region for v3 Nylas applications and v2 organizations. Each data center region is isolated, and data is not shared between regions. For information on setting up a new Nylas organization and configuring your data residency region for the first time, see Data residency.
💡 Using multiple data centers has no additional platform fee. See the billing documentation for more information.
Migrate existing v3 Nylas application
The following sections describe how to migrate an existing v3 Nylas organization to a new data residency region. Unlike the migration process for v2, you don't need to create an organization for the new data center. Instead, you migrate individual Nylas applications.
Create Nylas application and set up authentication
First, create a Nylas application for the region that you plan to migrate to and set up its authentication information. Check the application's configuration settings to make sure they're correct before you continue.
Migrate grants
There are two methods you can use to migrate grants from your old Nylas application to the new one:
Same-month or immediate migration
For this method, migrate all grants after you finish setting up your new Nylas application. Be sure to finish migrating the grants within the month, and contact Nylas' Billing team for charge adjustments.
Migrate new accounts first
After you finish setting up your new Nylas application, you can choose to have new end users authenticate in the new region, and migrate existing grants using a targeted approach. With this method, you can move information from your old Nylas application to the new one at your discretion.
This strategy helps mitigate additional work when setting up new users' grants.
Re-authenticate grants
Your end users' grants need to be re-authenticated in your new application's region. They also need new <ACCESS_TOKEN> values for your application.
Delete duplicate grants
Make a POST /v3/connect/revoke request to revoke the credentials for grants associated with your old Nylas application. This also removes access to the application for these grants.
Manage migrated data in v3
The following sections describe how to manage data as you migrate your Nylas application to a new region.
🔍 Unique identification values differ between Nylas applications in different regions. Any grant_id or object ID values in your old Nylas application are different than those in the application you created for migration.
Migrate v3 object data and update IDs
When you migrate your end users, their grants are considered new connections in Nylas. Because of this, all their data must be fetched again, and Nylas creates new ID values for every object. To connect the data, you can merge the information from your old Nylas application to the objects in your new Nylas application using the unique Calendar and Email object IDs.
Update v3 webhook configurations
After your Nylas application is set up in the new region, you must update your webhook configurations for the new data residency settings.
Update v3 Nylas SDK configurations
If you use the Nylas SDKs with your application, you must update their configurations to use the appropriate URL for your application's new region. See Configure base API URL in Nylas SDKs for more information.
Migrate existing v2 Nylas organization
The following sections describe how to migrate an existing v2 Nylas organization to a new data residency region.
📝 When you configure your Nylas organization to store data in one region, your Nylas application uses that region's URLs for API requests.
Create Nylas organization
First, create a Nylas application for the region that you plan to migrate to. Use the links below for your specific region's Nylas Dashboard.
| Location | Dashboard URL | API URL | Scheduler API URL |
|---|---|---|---|
| United States (Oregon) | https://dashboard.nylas.com |
https://api.nylas.com |
https://api.schedule.nylas.com |
| Europe (Ireland) | https://ireland-dashboard.nylas.com |
https://ireland.api.nylas.com |
https://ireland.api.schedule.nylas.com |
Set up authentication and begin migration
Next, set up your new Nylas application's authentication information (see Developing with Nylas for more information). Check the application's configuration settings to make sure they're correct, then begin migrating the new application into your organization.
Transfer billing information
Contact your Nylas Customer Success Manager with your new application's information — they'll connect the application's billing profile to your organization's account. The Billing department also manages the added data residency region for the application.
Migrate connected accounts
The methods for migrating connected accounts are the same as those for migrating grants:
⚠️ Connected accounts that are associated to both Nylas applications are considered billable. Be sure to deactivate the account associated with your old Nylas application to avoid being billed twice.
Re-authenticate connected accounts
Your end users' connected accounts need to be re-authenticated in your new application's region. They also need new <ACCESS_TOKEN> values for your application.
Delete duplicate connected accounts
Make a POST /oauth/revoke request to revoke the credentials for connected accounts associated with your old Nylas application. This also removes access to your old Nylas application for these connected accounts.
Update billing
Your organization uses more than one Nylas application when migrating between regions. Data for connected accounts remains in isolated regions, so you need to contact Nylas Support to ensure your billing profile is linked to your new Nylas application. You can also contact Nylas' Billing department for solutions when transitioning your application's data residency.
You should also update the billing state for accounts associated with your old Nylas application as quickly as possible. To do so, contact Nylas Support and include your applications' ID numbers.
Manage migrated data in v2
The following sections describe how to manage data as you migrate your Nylas organization to a new region.
🔍 Unique identification values differ between Nylas applications in different regions. Any account_id or object ID values in your old Nylas application are different than those in the application you created for migration.
Migrate v2 object data and update IDs
When you migrate your end users, their accounts are considered new connections in Nylas. Because of this, all their data must be re-synced, and Nylas creates new ID values for every object. To connect the data, you can merge the information from your old Nylas application to the objects in your new Nylas application using the unique Calendar and Email object IDs.
For Email objects, use the RFC-based messageid in the header of each email message. For Calendars using Nylas API v2.1+, use the ical_uid field in each Event object.
Update v2 webhook configurations
After your new Nylas application is set up in the new region, you must update your webhook configurations for the new data residency settings.
Update v2 Nylas SDK configurations
If you use the Nylas SDKs with your application, you must update their configurations to use the appropriate URL for your application's new region. See Configure base API URL in Nylas SDKs for more information.