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 Agent Accounts, Nylas provisions the primary calendar when it creates the account, and you can't delete it.

For iCloud, there is no primary calendar.

Free/Busy information

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

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

Agent Account calendars

When you need a calendar for a user or resource that has no account on a provider (for example, an external contractor, a meeting room, or an AI agent), create an Agent Account. Every Agent Account is a Nylas-hosted mailbox with a primary calendar, so all of the Calendar endpoints work on its grant, and it can send invitations, receive invitations from other calendars, and respond with an RSVP. Agent Accounts also work with the Email and Contacts APIs and with Scheduler.

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.