Only show these results:
public-beta-v3

Create Grants for Virtual Calendars in v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

Virtual Calendars are Nylas' implementation of a calendar and events provider. Functionally, you can think of them as another provider like Google or Microsoft, but one that is limited to calendaring only. You can access Virtual Calendars through an auth integration just like any other provider, and use the same Calendar and Events APIs to interact with them.

Virtual Calendars are ideal for situations where you need to schedule events for people or objects that aren’t associated with an existing Calendar account. Virtual Calendars allow you to provide scheduling functionality to your users without requiring them to connect a third-party service provider like Google, Exchange, or Office 365.

For more details on Virtual Calendars, see the Virtual Calendars documentation. Although this page was written for v2.x, the description of the Virtual Calendar is still mostly correct.

What changed from v2 to v3?

  • Virtual Calendars are no longer limited to one Calendar per account (now called a Grant). You can now have 10 calendars per Grant.
    • As in v2, you can create as many Grants as you need, and you are billed per Grant.
    • You can create Calendars using the POST /v3/calendars endpoint.
  • You must provide an identifier when you create the Grant for Virtual Calendars. Previously, this was optional. This can be any arbitrary string, and no longer needs to be in email address format.
  • Virtual Calendars use the new v3 Nylas Calendar and Events APIs, and all Calendar-related endpoint changes in v3 API also apply to Virtual Calendars.

Set up a Virtual Calendar in v3

The following sections describe how to set up a Virtual Calendar in Nylas v3.

Create a v3 Nylas connector

Nylas connectors store information that allows your Nylas application to connect to service providers. In this case the provider is Nylas, and you specify virtual-calendar to indicate that:

{
  "name": "My New App",
  "provider": "virtual-calendar"
}

Virtual Calendars do not support the concept of "scopes" (levels of access), so do not include any during the authentication process.

Learn More

See our POST /v3/integrations documentation for more information on creating a connector.

Create a new Grant for the Virtual Calendar

Next, you must create a Grant representing the account or end user that the Virtual Calendar is for. In v3, Grants replace the concept of "Connected Accounts".

You must specify an identifier when you create a Grant. This can be any string, though it may be helpful to use an email address.

Note: Some endpoints (such as the availability endpoint) include validation that relies on the Grant associated with an email address. If there are multiple Grants associated with a single email address in your Nylas application, this validation could fail.

To avoid this, use a unique email address or identifier when creating a Grant for a Virtual Calendar, especially if it is for an end-user who is using other features besides Virtual Calendar.

{
  "provider": "virtual-calendar",
  "settings": {
    "email": "[email protected]"
  }
}

Learn More

See our POST /v3/grants documentation for more information on creating a Grant.

What's next?

When you have authentication set up, you're done! You can now start using Virtual Calendars just as you would any other provider.