Only show these results:

Virtual calendars overview

Virtual calendars work like any other calendar in Nylas, and make it easy to include customized scheduling in your Nylas application. They're ideal for situations where you need to schedule events for people or objects that aren't associated with an existing account (for example, a meeting room). Virtual calendars allow you to provide scheduling to your end users without requiring them to connect a third-party service provider like Google, Microsoft Exchange, or Office 365.

There are two major scheduling use cases for virtual calendars:

  • Enabling scheduling for end users who have sensitive data in their personal calendars that they don't want to expose to complete their task.
  • Enabling scheduling for people or resources that don't have an account on a third-party service provider.
ℹ️ Virtual Calendars is available for Core and Plus plans.

A diagram showing how virtual calendars integrate with a Nylas application.

How virtual calendars work

Virtual calendars are associated with virtual accounts — Connected Accounts or grants that represent a person or resource. Virtual accounts can be used as part of any Nylas application, and can be created using Custom auth in v3.

You create a virtual account by passing the client ID of your Nylas application. Each application can have multiple virtual accounts, but each v3 virtual account can have only ten virtual calendars.

After you create a virtual account, you can create a virtual calendar. The virtual calendar's email field becomes its unique ID. Nylas uses the email field to manage the calendar's account.

⚠️ The account listed in a virtual calendar's email field cannot be used as a regular email account. Nylas strongly recommends against using an existing email address for this field.

The following JSON snippet shows the schema for a virtual calendar.

{
"client_id": "3",
"provider": "nylas",
"scopes": "calendar",
"email": "virtual_account_unique_id",
"name": "Virtual Calendar",
"settings": {}
}

After Nylas creates your virtual calendar, it appears in the Nylas Dashboard as a connected account. A virtual calendar's provider is always listed as Nylas, as in the image below.

The Nylas Dashboard showing a list of calendars. The virtual calendar has no Account Type, and its Provider is listed as Nylas.

Virtual calendar webhooks

Virtual calendars support the following Calendar and Event webhooks:

  • calendar.created
  • event.created
  • event.updated

For more information, see the Calendar webhook schemas and Event webhook schemas.

Keep in mind

You should keep the following things in mind when you work with virtual calendars:

  • The Nylas Scheduler supports virtual calendars.
  • Virtual calendars support notifications for events.
  • Virtual calendars can interact with the Account, Calendar, and Events endpoints only.
  • Each virtual account is limited to ten virtual calendars.
  • In Nylas v3, the first virtual calendar that you create for a virtual account is designated the account's primary calendar.