Calendar

The Nylas Calendar API allows you to create and manage calendars, and access the events they contain. Nylas uses the same commands to manage calendars across providers, and you can refer to specific calendars using the provider's calendar_id.

Depending on the provider, a calendar might be accessed by only one person, or shared among several users. Some common calendars might include Personal, Work, or Shared calendars.

A calendar might contain overlapping events or conflicting schedules. You can use the Get Availability endpoint to find the best time for an event by identifying time periods that have no conflicting events among all participants.

Find a calendar ID

You must specify a calendar_id in all calls you make to the Nylas Calendar API. You can use primary to specify the primary calendar associated with a grant, or you can look up the ID of the calendar that you want to work with and use that.

For virtual calendars, the primary calendar is the first created for a virtual account. You cannot delete a virtual calendar that's designated as primary.

For iCloud, there is no primary calendar.

Free/Busy information

The Get Free/Busy Schedule endpoint is available for all providers, including Virtual Calendars, except for iCloud.

The Get Availability endpoint doesn't support the free_busy object.

Virtual calendars

Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.

For more information, see Using virtual calendars.

Metadata on calendars

You can add metadata to new and existing calendars by including the metadata sub-object in your POST, PUT, or PATCH request. For more information, see the Metadata documentation.

Calendar scopes

The table below lists the Calendar endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

For more information about scopes, see Using scopes to request user data.

Calendar activity notifications

You can subscribe to the following triggers so Nylas notifies you about changes to your users' calendar data:

• calendar.created
• calendar.updated
• calendar.deleted

For more information, see the Calendar webhook notification schemas.

Microsoft event considerations

Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.