hero banner

A small guide to Virtual Calendars

6 min read

For any business, using a calendar to create and manage events is an essential asset to maintaining current customers and attracting new prospects. But sometimes, using a regular calendar is not enough or it’s not feasible. When there’s the need to create an event for gym equipment, Zumba class, to reserve an office space or when we need to create an event for someone not working in our company, then a virtual calendar is the way to go, and this guide is all you need.

Special thanks to Allison Bradley, our Solutions Engineer II for guiding me into Virtual Calendars.

What are we going to talk about?

What are Virtual Calendars?

Virtual Calendars are calendars that are tied to your Nylas account, so they are independent of any calendar provider. A virtual calendar will handle one event at a time.

Connected accounts diagram

How do Virtual Calendars work?

To create a virtual calendar, you need to assign a non-working email address, which will become its unique identifier. Nylas will use that identifier to manage the calendar account.

In order to create a Virtual Calendar we need to first create a Virtual Account. An application can have multiple virtual accounts, but only one virtual calendar can be associated with a virtual account.

Creating a Virtual Calendar

First, we need to create a virtual account, which uses native authentication. So just copy and paste the following cURL call into a terminal window:

$ curl --location --request POST 'https://api.nylas.com/connect/authorize' --data-raw '{
    "client_id": "<YOUR_CLIENT_ID>",
    "provider": "nylas",
    "scopes": "calendar", 
    "email": "nylas_gym_calendar",
    "name": "Virtual Calendar",
    "settings": {}

Keep in mind that nylas_gym_calendar is the non-working email that we are using.

To get your client id you can go into your Nylas Dashboard.

This will return a code that we will use in the next step when we generate an access token:

Generate authorization

Now, we need to pass our client id, client secret and the code generated in the previous step:

$ curl --location --request POST 'https://api.nylas.com/connect/token' --data-raw '{
        "client_id": "<YOUR_CLIENT_ID>",
        "client_secret": "<YOUR_CLIENT_SECRET>",
        "code": "<YOUR_CODE>"

This will generate the access token:

Generate access token

But also will create a new application in our Nylas’ dashboard:

Connected account (with Virtual Calendar)

With the virtual account already created, we can proceed and create our virtual calendar. 

Keep in mind that only one virtual calendar per virtual account is allowed:

$ curl --location --request POST 'https://api.nylas.com/calendars' --header 'Authorization: Bearer <ACCESS_TOKEN>' --data-raw '{
            "name":"Nylas'' Gym Equipment",
            "description":"Reserve your Gym Equipment",
            "location":"Ottawa, Canada",

After executing this code, we will have our virtual calendar ready to use:

Creating a Virtual Calendar

Creating an event on a Virtual Calendar

We can create an event, just like we would do using a regular calendar, with the exception of using the Virtual Access Token and the Virtual Calendar Id:

Create an event on a Virtual Calendar

Here’s the curl call:

$ curl --location --request POST 'https://api.nylas.com/events' \
    --header 'Authorization: Bearer <VIRTUAL_ACCESS_TOKEN>' \
    --data-raw '{
        "title":"Gym equipment reservation at 2:00pm",
        "when" : {
            "start_time": 1672408800,
            "end_time": 1672412400
        "location": "Nyla''s Gym",
        "calendar_id": "<VIRTUAL_CALENDAR_ID>",
        "participants": [ 
                "email": "someone@gmail.com",
                "name": "Someone"             

And here’s the response:

Event on Virtual Calendar response

As we can see we get all the relevant information back and the owner has displayed a Virtual Calendar <nylas_gym_calendar>.

One important thing to keep in mind is that Virtual Calendars don’t send email notifications, so while I have been invited to this event, I have not received any email confirmation. But don’t let that scare you away, there’s a way to overcome this.

Generate an ICS file

An ICS (Internet Calendar Scheduling) file can be generated by using an event id:

$ curl --location --request POST 'https://api.nylas.com/events/to-ics' \
--header 'Authorization: Bearer <VIRTUAL_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "event_id": "<EVENT_ID>"
}' -o invite.ics
Generate ICS file

This will download the file in json format, but it will not usable unless we extract what we need.

In order to do that we can use jq a sed like tool for json data. We can install by using Brew:

$ brew install jq

Once installed, we can use to format our invite.ics file:

$ jq '(.ics)' --raw-output invite.ics > invitation.ics

This will transform our invite.ics file into invitation.ics keeping only the information we need and in the format that we need it.

Upload a file

In order to upload a file, we need to use our regular access token, as the one use for our virtual calendar will not work:

$ curl --request POST \
  --url https://api.nylas.com/files \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form 'file=@<PATH>/invitation.ics'
Upload ICS file

With the id of the uploaded file, we can now send an email confirmation.

Sending an email

Now, we’re ready to send a confirmation email to the participant. Here’s the cURL call:

$ curl --request POST \
  --url https://api.nylas.com/send \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "subject": "From Nyla''s Gym",
  "to": [
      "email": "<PARTICIPANT_EMAIL>",
      "name": "Blag"
  "body": "Thanks for reserving our Gym Equipment",
  "file_ids": [

And here’s the terminal call:

Send an email with an ICS attachment

And its corresponding response:

Response from email with ICS attachment

We can now check our email to confirm that indeed, we received the email:

Event created in Calendar

Perfect. We can simply view it on our Google Calendar and confirm that we’re going.

Virtual Calendars are a powerful way to handle your calendar needs, and this guide should be your number one resource.

Is there an easier way?

Of course, we provide four SDKs: Ruby, Java, Node.js and Java. They are all prepared to work with Virtual Calendars and make our lives easier and our coding time shorter.

Also, if you want to learn more about Virtual Calendars, read our documentation Virtual Calendars Overview.

Don’t miss the action, join our LiveStream Coding with Nylas:

Related resources

How to create and read Google Webhooks using Ruby

Create and read your Google webhooks using Ruby and Sinatra, and publish them using Koyeb. Here’s the full guide.

Build mail merge and email templates using TinyMCE Rich Text Editor

Learn how to build Mail Merge and Email Template functionality in your email workflow using TinyMCE Rich Text Editor.

Send emails using TinyMCE Rich Text Editor

Learn how to improve your email workflow using TinyMCE Rich Text Editor.