Skip to content

Using virtual calendars

Virtual calendars work like any other calendar in Nylas, and they make it easy to include customized scheduling in your Nylas application. They let you provide scheduling features to your users without requiring them to connect a third-party service provider like Google or Microsoft.

There are two major use cases for virtual calendars:

  • Enabling scheduling for users who have sensitive information on their personal calendars that they don’t want to expose to complete their task.
  • Enabling scheduling for users or resources that don’t have accounts on the usual providers, such as external contractors or meeting rooms.

How virtual calendars work

Virtual calendars are linked to virtual accounts (“grants”), and can represent a person or resource that doesn’t otherwise have a calendar. You can use virtual accounts as part of any Nylas application. Unlike normal grants, virtual accounts can’t become invalid (they don’t expire), they don’t generate grant.expired notifications, and you don’t need to select scopes for them. You can delete virtual accounts by making a Delete Grant request.

You can create virtual accounts using a Virtual Calendar connector and Custom Authentication. Each Nylas application can have as many virtual accounts as needed, billed at your usual per-account price, and each virtual account can have up to 10 virtual calendars.

Virtual calendars appear in the Nylas Dashboard as grants, and their provider is always listed as “Virtual Calendar”.

The Nylas Dashboard showing a list of grants. The virtual calendar's Provider is listed as Virtual Calendar.

When you create a virtual account, the email field you specified becomes its unique ID, which you use in requests to manage the calendar’s account. After you create the account, you can create virtual calendars for it.

The first virtual calendar that you create for a virtual account becomes the account’s primary calendar. Like normal calendars, you can reference the virtual calendar in API calls using the primary keyword instead of the calendar_id. You can’t change which virtual calendar is the primary calendar, and you can’t delete the primary calendar.

You can use virtual calendars to book meetings using Nylas Scheduler.

Set up virtual calendars

Before you create a virtual calendar, create a Nylas application, generate an API key for the application, and set up your authentication flow.

Authenticate a virtual account

There are two steps to authenticating a virtual account: first, you have to create a Virtual Calendar connector, then create a virtual account.

Create a Virtual Calendar connector

Before you can create a virtual calendar, you need a Virtual Calendar connector. You can create a connector from the Nylas Dashboard, by making a request to the POST /v3/connectors endpoint, or using the Nylas SDKs. You only need to create one Virtual Calendar connector for each application.

Create a virtual account

Now, you can create a grant for the virtual account. This grant represents the “owner” of the account.

Virtual accounts use Custom Authentication only. You can use the same auth process each time you need to create a virtual account.

The following cURL request is an example of a Custom Authentication request for a new virtual account.

curl --request POST
--url https://api.us.nylas.com/v3/connect/custom \
--header 'Accept: application/json, application/gzip' \
--header 'Authorization: Bearer <NYLAS_API_KEY>'\
--header 'Content-Type: application/json' \
--data '{
"provider": "virtual-calendar",
"settings": {
"email": "<VIRTUAL_ACCOUNT_IDENTIFIER>"
},
"state": "<STATE>"
}'

The email field can contain any arbitrary string and doesn’t need to be email-formatted. Nylas uses the email value as an ID to manage the virtual account. Because of this, you can’t use the identifier listed in the email field as a regular email account with Nylas. Nylas strongly recommends against using an existing email address for this field.

Nylas returns information about the new virtual account, including its grant ID.

{
"request_id": "1",
"data": {
"id": "<NYLAS_GRANT_ID>",
"provider": "virtual-calendar",
"grant_status": "valid",
"email": "<VIRTUAL_ACCOUNT_IDENTIFIER>",
"scope": [],
"user_agent": "string",
"ip": "string",
"state": "<STATE>",
"created_at": 1617817109,
"updated_at": 1617817109
}
}

You can also use the Nylas SDKs to authenticate a virtual account, as in the following examples.

Create a virtual calendar

Now that you’ve authenticated a virtual account, you can make a Create Calendar request or use the Nylas SDKs to create a virtual calendar.

Create an event on a virtual calendar

When you have both a virtual account and a virtual calendar, you can start creating events.

To create an event on a virtual calendar, you can either make a Create Event request or use the Nylas SDKs.

Get availability for virtual calendars

You can use the Get Availability endpoint to get availability information for virtual calendars. The following cURL request uses the virtual account’s id in the email field, and specifies the primary calendar.

Virtual calendar notifications

Virtual calendars support the following Calendar and Events notifications:

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

You can subscribe to these notifications by setting up webhook subscriptions or a Pub/Sub notification channel.