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 allow you to provide scheduling to your end users without requiring them to connect a third-party service provider like Google or Microsoft.

ℹ️ Virtual calendars is available for Free, Core, and Plus plans. Available for demo in the Free-tier Sandbox.

There are two major scheduling use cases for virtual calendars:

Enabling scheduling for end users who have sensitive information in their personal calendars that they don't want to expose in order to complete their task.
Enabling scheduling for people or resources that don't have an account on a third-party service provider (for example, a meeting room).

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. You create them using a Virtual Calendar connector and Custom authentication. Each Nylas application can have multiple virtual accounts, and each virtual account can have up to 10 virtual calendars.

After you create a virtual account, you can create a virtual calendar. The calendar's email field becomes its unique ID, which you use in requests to manage the calendar's account.

Virtual calendars appear in the Nylas Dashboard as connected accounts. A virtual calendar's provider is always listed as "Nylas".

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.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connectors' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "provider": "virtual-calendar",
    "name": "nylas"
}'

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function createConnector() {
  try {
    const connector = await nylas.connectors.create({
      requestBody: {
        name: 'nylas',
        provider: 'virtual-calendar',
      }
    })

    console.log('Connector created:', connector)
  } catch (error) {
    console.error('Error creating provider:', error)
  }
}

createConnector()

from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

connector = nylas.connectors.create(
    request_body={
      "name": 'nylas',
      "provider": "virtual-calendar"
    }
)

print(connector)

require 'nylas'

nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')

request_body = {
  name: 'Nylas',
  provider: 'virtual-calendar'
}

begin
  nylas.connectors.create(request_body: request_body)
rescue Exception => exception
  puts exception
end

import com.nylas.NylasClient;
import com.nylas.models.*;

public class connector {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    CreateConnectorRequest request = new CreateConnectorRequest.VirtualCalendar();
    Response<Connector> connectorResponse = nylas.connectors().create(request);

    System.out.println(connectorResponse);
  }
}

import com.nylas.NylasClient
import com.nylas.models.CreateConnectorRequest

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val request = CreateConnectorRequest.VirtualCalendar()
  val connector = nylas.connectors().create(request)

  print(connector.data)
}

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' \
  --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.

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function createVirtualCalendarGrant() {
  try {
    const response = await nylas.auth.grants.create({
      requestBody: {
        provider: 'virtual-calendar',
        settings: {
          email: 'devrel-virtual-calendar',
        },
        scope: ['calendar']
      }
    })

    console.log('Grant created:', response)
  } catch (error) {
    console.error('Error creating grant:', error)
  }
}

createVirtualCalendarGrant()

from dotenv import load_dotenv
load_dotenv()
import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = nylas.auth.custom_authentication(
    request_body={
      "provider": "virtual-calendar",
      "settings": {
        "email": 'devrel-virtual-calendar',
      },
      "scope": ['calendar']
    }
)

print(grant_id)

# frozen_string_literal: true

require 'nylas'
require 'sinatra'

set :show_exceptions, :after_handler

error 404 do
  'No authorization code returned from Nylas'
end

error 500 do
  'Failed to exchange authorization code for token'
end

nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')

get '/nylas/auth' do
  request_body = {
    provider: 'virtual-calendar',
      settings: {
        email: "nylas-virtual-calendar" 
      }
    }

    response = nylas.auth.custom_authentication(request_body)
    "#{response}"
end

import java.util.*;
import static spark.Spark.*;
import com.nylas.NylasClient;
import com.nylas.models.*;

public class AuthRequest {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    get("/nylas/auth", (request, response) -> {
      Map<String, String> settings = new HashMap<>();
      settings.put("email", "nylas-virtual-calendar");

      List<String> scopes = new ArrayList<>();
      scopes.add("openid");

      CreateGrantRequest requestBody = new CreateGrantRequest.
          Builder(AuthProvider.VIRTUAL_CALENDAR, settings).
          scopes(scopes).state("xyz").
          build();

      Response<Grant> authResponse = nylas.auth().customAuthentication(requestBody);

      return "%s".formatted(authResponse);
    });
  }
}

import com.nylas.NylasClient
import com.nylas.models.*
import spark.kotlin.Http
import spark.kotlin.ignite

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")
  val http: Http = ignite()

  http.get("/nylas/auth") {
    val settings = mapOf("email" to "nylas-virtual-calendar")
    val scopes = listOf("openapi")

    val requestBody = CreateGrantRequest.
        Builder(AuthProvider.VIRTUAL_CALENDAR, settings).
        scopes(scopes).
        state("xyz").
        build()

    var authResponse : Response<Grant>

    nylas.auth().customAuthentication(requestBody).also { authResponse = it }

    authResponse
  }
}

Create a virtual calendar

💡 Tip! You can create up to 10 virtual calendars per virtual account.

Now that you've authenticated a virtual account, you can make a POST /v3/grants/<NYLAS_GRANT_ID>/calendars request or use the Nylas SDKs to create a virtual calendar.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "name": "Nylas DevRel",
    "description": "Nylas Developer Relations"  
}'

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
 apiKey: process.env.NYLAS_API_KEY,
 apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function createVirualCalendar() {
  try {
    const calendar = await nylas.calendars.create({
      identifier: process.env.VIRTUAL_CALENDAR_GRANT_ID,
      requestBody: {
        name: 'Nylas DevRel',
        description: 'Nylas Developer Relations',
      }
    })

    console.log('Virtual Calendar:', calendar)
  } catch (error) {
    console.error('Error to create virtual calendar:', error)
  }
}

createVirualCalendar()

from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("VIRTUAL_CALENDAR_GRANT_ID")

calendar = nylas.calendars.create(
  grant_id,
  request_body={
    "name": 'Nylas DevRel',
    "description": 'Nylas Developer Relations'
  }
)

print(calendar)

require 'nylas' 

nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')

request_body = {
  "name": "Nylas DevRel",
  "description": "Nylas Developer Relations",
  "timezone": "America/Toronto"
}

begin
  calendars, _request_ids = nylas.calendars.create(
      identifier: '<VIRTUAL_CALENDAR_ID>', 
      request_body: request_body)

  puts calendars
rescue Exception => exception
  puts exception
end

import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.HashMap;

public class CreateVirtualCalendar {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

    CreateCalendarRequest requestBody = new CreateCalendarRequest(
        "Nylas DevRel",
        "Nylas Developer Relations",
        "Nylas Headquarters",
        "America/Toronto",
        new HashMap<String, String>());

    try {
      Response<Calendar> calendar = nylas.calendars().create(
          "<VIRTUAL_CALENDAR_GRANT_ID>", 
          requestBody);

      System.out.println(calendar);
    } catch(Exception e) {
      System.out.printf(" %s%n", e);
    }
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
  val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

  val requestBody = CreateCalendarRequest(
      "Nylas DevRel",
      "Nylas Developer Relations",
      "Nylas Headquarters",
      "America/Toronto",
      mapOf<String, String>()
  )

  val calendar: Response<Calendar> = nylas.calendars().create(
      "<VIRTUAL_CALENDAR_GRANT_ID>", 
      requestBody)
      
  print(calendar.data)
}

The first virtual calendar you create for a virtual account becomes the "primary" calendar. You can reference it in future requests using primary instead of the calendar_id. You can't change which calendar is the primary for the virtual account, and you can't delete the primary calendar.

Create an event on a virtual calendar

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

⚠️ Virtual calendars do not send email invitations to event participants.

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

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&notify_participants=true' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data '{
    "when": {
      "start_time": 1704302073,
      "end_time": 1704305673
    },
    "title": "Build With Nylas"
}'

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI
}

const nylas = new Nylas(NylasConfig)
const now = Math.floor(Date.now() / 1000)

async function createAnEvent() {
  try {
    const event = await nylas.events.create({
      identifier: process.env.VIRTUAL_CALENDAR_GRANT_ID,
      requestBody: {
        title: 'Build With Nylas',
        when: {
          startTime: now,
          endTime: now + 3600,
        }
      },
      queryParams: {
        calendarId: process.env.VIRTUAL_CALENDAR_ID,
      },
    })

    console.log('Event:', event)
  } catch (error) {
    console.error('Error creating event:', error)
  }
}

createAnEvent()

from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("VIRTUAL_CALENDAR_GRANT_ID")
calendar_id = os.environ.get("VIRTUAL_CALENDAR_ID")

events = nylas.events.create(
    grant_id,
    request_body={
      "title": 'Build With Nylas',
      "when": {
        "start_time": 1609372800,
        "end_time": 1609376400
      },
    },
    query_params={
      calendar_id
    }
)

print(events)

require 'nylas'

nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')

query_params = {
  calendar_id: '<VIRTUAL_CALENDAR_ID>'
}

start_time = Time.now.to_i
end_time = start_time + 3600

request_body = {
  when: {
    start_time: start_time,
    end_time: end_time
  },
  title: "Build With Nylas",
}

events, _request_ids = nylas.events.create(
    identifier: '<VIRTUAL_CALENDAR_GRANT_ID>',
    query_params: query_params, 
    request_body: request_body)
    
if _request_ids != "" 
  puts events[:id]
  puts events[:title]
  puts "Event created successfully"
else
  puts "There was an error creating the event"
end

import com.nylas.NylasClient;
import com.nylas.models.*;

public class CreateVirtualEvent {
	public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
		NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

		CreateEventRequest.When.Timespan timespan = new CreateEventRequest.When.Timespan.
				Builder(Math.toIntExact("<START_TIME>"),
				Math.toIntExact("<END_TIME>")).
				build();

		CreateEventRequest request = new CreateEventRequest.Builder(timespan).
				title("Build With Nylas").
				build();

		CreateEventQueryParams queryParams = new CreateEventQueryParams.Builder("<VIRTUAL_CALENDAR_ID>").build();
		
		Response<Event> event = nylas.events().create(
				"<VIRTUAL_CALENDAR_GRANT_ID", 
				request,
				queryParams);
				
		System.out.println(event);
	}
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
	val nylas: NylasClient = NylasClient(apiKey = "<NYLAS_API_KEY>")

	val eventWhenObj: CreateEventRequest.When = CreateEventRequest.When.Timespan(<START_TIME>, <END_TIME>)

	val eventRequest: CreateEventRequest = CreateEventRequest.Builder(eventWhenObj).
			title("Nylas DevRel").
			description("Nylas Developer Relations").
			location("Nylas Headquarters").
			build()

	val eventQueryParams: CreateEventQueryParams = CreateEventQueryParams("<VIRTUAL_CALENDAR_ID>")

	val event: Response<Event> = nylas.events().create(
			"<VIRTUAL_CALENDAR_GRANT_ID>",
			eventRequest, 
			eventQueryParams)
			
	print(event.data)
}

Get availability for virtual calendars

You can use the 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.

Request
Response (JSON)

curl --request POST \
  --url https://api.us.nylas.com/v3/calendars/availability \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [
      {
        "email": "<VIRTUAL_ACCOUNT_ID>",
        "calendar_ids": [
          "primary"
        ],
        "open_hours": [{
          "days": [
            0,
            1,
            2
          ],
          "timezone": "America/Toronto",
          "start": "9:00",
          "end": "17:00",
          "exdates": []
        }]
      }
    ],
    "start_time": 1600890600,
    "end_time": 1600999200,
    "interval_minutes": 30,
    "duration_minutes": 30,
    "round_to": 15,
    "availability_rules": {
      "availability_method": "max-availability",
      "buffer": {
        "before": 15,
        "after": 15
      },
      "default_open_hours": [
        {
          "days": [
            0,
            1,
            2
          ],
          "timezone": "America/Toronto",
          "start": "9:00",
          "end": "17:00",
          "exdates": []
        },
        {
          "days": [
            3,
            4,
            5
          ],
          "timezone": "America/Toronto",
          "start": "10:00",
          "end": "18:00",
          "exdates": []
        }
      ]
    }
  }'

{
  "request_id": "1",
  "data": {
    "time_slots": [
      {
        "emails": [
          "<VIRTUAL_ACCOUNT_ID>"
        ],
        "start_time": 1659367800,
        "end_time": 1659369600
      },
      {
        "emails": [
          "<VIRTUAL_ACCOUNT_ID>"
        ],
        "start_time": 1659376800,
        "end_time": 1659378600
      }
    ]
  }
}

Virtual calendar notifications

Virtual calendars support the following Calendar and Events notifications:

calendar.created
event.created
event.updated

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

Keep in mind

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

Nylas Scheduler supports virtual calendars.
Virtual calendars can interact with the Grants, Calendar, and Events endpoints only.