Upgrade a v2 project to use v3 Calendar APIs
This page explains what you need to do to upgrade your projects to use the Nylas v3 Calendar API.
The first step for every project migrating from Nylas v2.x to Nylas v3 is to assess and upgrade your authentication systems. Once you have your authentication working using v3, you can then upgrade your project to use the v3 Calendar API.
✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!
Recap: General updates in v3
You should already be aware of these changes, but as a reminder:
The Nylas API endpoints and production domains have changed in v3. They now follow the [service].[region].nylas.com schema:
api.nylas.com→api.us.nylas.comcanada.api.nylas.com→api.us.nylas.comireland.api.nylas.com→api.eu.nylas.com
In v3, Nylas removes the concept of "connected accounts" and instead works with "Grants". The grant_id for an account is used as a locator in most requests, so you may need to look up the user's grant_id before you can make API calls on their behalf.
Nylas v3 removes the concept of "Nylas Scopes" and uses the provider's scopes directly. See the Scopes documentation for more details. If you're authenticating with Microsoft, you must also translate your v2 application's scopes into the new Microsoft Graph scopes used in v3.
Coming soon and deprecated endpoints
Calendar and Events endpoints are available for Google, Microsoft Graph, iCloud, Exchange on-prem, and virtual calendars in Nylas v3. Updates to Scheduler are also coming soon.
The Return room resources information endpoint (GET /resources) is in progress and coming soon to v3.
The Multiple consecutive meetings availability endpoint (POST /calendars/availability/consecutive) has been removed. The Generate ICS file endpoint (POST /events/to-ics) is not available.
If your project requires any of these endpoints, contact Nylas Support before you begin the upgrade process.
Architecture changes
Nylas v3 no longer syncs data from providers, but instead queries them directly. This means that Nylas now relies on the provider as the source of truth, however some providers may require tuning to best handle their differing behavior. This is especially true for recurring events.
Nylas no longer generates an "Emailed Events" calendar for IMAP accounts in v3.
Syntax changes in v3
In v3 a Calendar ID is required for almost all calls. However, Nylas v3 includes a new endpoint that allows you to GET all calendars that a user has access to.
You can approach finding the calendar ID in the following ways:
- Get a list of all calendars for the grant ID, and find the ID of the calendar you want to work with, and use that.
- Use the
primaryparameter to specify the main calendar associated with the Grant on the service provider.- For virtual calendars, the
primarycalendar is the first calendar created for a grant. You cannot delete the primary calendar. - iCloud calendars do not have a
primarycalendar, so you need to query for the ID first.
- For virtual calendars, the
Changes to Metadata filters
In Nylas v2, you could add up to 50 pairs of arbitrary metadata key-pairs to Calendars, Events, and Messages, and use those keys as query parameters to filter data from Nylas. This sometimes led to high latency when returning results.
In Nylas v3, you can still add metadata key pairs, however Nylas only indexes five specific keys: key1, key2, key3, key4, and key5. To continue using metadata filtering, you must write the values you want to filter by to the keys that Nylas indexes.
Nylas uses the key5 value when calculating round robin order. If you're using round-robin scheduling, you might want to make a plan for how you distribute queryable metadata among the five keys. Additionally, you can't use metadata filters with provider value filters, except for calendar_id.
Nylas v3 currently supports metadata on Calendars and Events only. Metadata support for other objects is coming soon.
Calendar Availability request changes
The endpoint to check for calendar availability (POST /calendars/availability) is unchanged, however some of its fields have been renamed for clarity. See the updated Calendar availability documentation, and the Availability v3 API reference for more details.
This endpoint does not require a grant ID or calendar ID because you can specify multiple participants to check for availability.
As a reminder for those of you who skip around when reading documentation (no shade), the Multiple consecutive meetings availability endpoint (POST /calendars/availability/consecutive) has been removed. If your project requires this endpoint, contact Nylas Support.
Recurring events in v3
The format for recurring Events has been simplified. Recurring Events no longer accept a recurrence timezone, and instead use the timezone specified in your when object to calculate the time for event instances. The when object is a time: in Unix timestamp format, and a timezone: in IANA format. See the Recurring events for more details.
Migrate Calendar endpoints
You can compare the v2 request schemas with the v3 request schemas.
- Return all calendars:
GET /calendars→GET /v3/grants/<grant_id>/calendars - Create a calendar:
POST /calendars→POST /v3/grants/<grant_id>/calendars - Return a calendar:
GET /calendars/<id>→GET /v3/grants/<grant_id>/calendars/<calendar_id> - Update a calendar:
PUT /calendars/<id>→PUT /v3/grants/<grant_id>/calendars/<calendar_id> - Delete a calendar:
DELETE /calendars/<id>→DELETE /v3/grants/<grant_id>/calendars/<calendar_id> - Check a calendar for free/busy status:
POST /calendars/free-busy→POST /v3/grants/<grant_id>/calendars/free-busy
Migrate Events endpoints
You can compare the v2 request schemas with the v3 request schemas.
- Return all Events:
GET /events→GET /v3/grants/<grant_id>/events - Create an Event:
POST /events→POST /v3/grants/<grant_id>/events - Return an Event:
GET /events/<id>→GET /v3/grants/<grant_id>/events/<event_id> - Update an Event:
PUT /events/<id>→PUT /v3/grants/<grant_id>/events/<event_id> - Delete an Event:
DELETE /events/<id>→DELETE /v3/grants/<grant_id>/events/<event_id> - Send RSVP:
POST /send-rsvp→POST /v3/grants/<grant_id>/events/<event_id>/send-rsvp
Calendar and event webhook triggers
The webhook triggers for calendar and events notifications have not changed, however Nylas has changed the webhook notification format and some behavior. Nylas now sends webhook notifications enriched with information about the object that changed, and does not send historical webhooks. See the Webhooks changes in v3 for more information about the changes, and the Calendar webhook schemas and Event webhook schemas for more information.
Tuning v3 queries
Service providers like Google and Microsoft implement strict rate limiting (more about that here). Because Nylas v3 queries the providers directly, it is important that you make sure your API requests limit the amount of data they request so you don't hit these provider rate limits.
To avoid this you can use filtering and query selection to limit both the number of objects Nylas queries, and the amount of data Nylas returns about those objects. For example, if you're searching for an event with a specific title, you would ignore other returned fields like the event description. To make an efficient query, you could use a title=<Your title here> query parameter, and then use select=title,id to make sure Nylas only returns the information you need.
See the Developer Guide best practices section to learn more about rate limiting.