Only show these results:

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 API v2.x to Nylas API 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.

Recap: General updates in API v3

You should already be aware of these changes, but as a reminder:

The Nylas API endpoints and production domains have changed in API v3. They now follow the [service].[region].nylas.com schema:

  • api.nylas.comapi.us.nylas.com
  • canada.api.nylas.comapi.us.nylas.com
  • ireland.api.nylas.comapi.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 API 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, IMAP, and Virtual Calendars in API v3. Microsoft Exchange Web Services is no longer supported, and Calendar and Events support is coming soon for iCloud. Updates to Scheduler are also coming soon.

The Generate ICS file POST /events/to-ics endpoint and the Return room resources information GET /resources endpoint are in progress and coming soon to API v3.

The Multiple consecutive meetings availability endpoint (POST /calendars/availability/consecutive) has been removed.

If your project requires any of these endpoints, contact Nylas Support before you begin the upgrade process.

Architecture changes

Nylas API 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.

Syntax changes in API 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 primary parameter to specify the main calendar associated with the Grant on the service provider.
    • For Virtual Calendars, the primary calendar is the first calendar created for a Grant, and it cannot be deleted.
    • iCloud calendars do not have a primary calendar, so you need to query for the ID first.

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 API 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 epoch time, 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 /calendarsGET /v3/grants/<grant_id>/calendars
  • Create a calendar: POST /calendarsPOST /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-busyPOST /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 /eventsGET /v3/grants/<grant_id>/events
  • Create an Event: POST /eventsPOST /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-rsvpPOST /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.