Build for free

Nylas
Blog
Calendar API
A Small Guide to Virtual Calendars

A Small Guide to Virtual Calendars

Blag aka Alvaro Tejada Galindo

Mar 21, 2023

This definitive guide will provide you with everything you need to know in order to work with Virtual Calendars.

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

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:

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:

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",
            "timezone":"America/Toronto"
    }'

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

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:

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:

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

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'

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": [
    "<FILE_ID>"
  ]
}'

And here’s the terminal call:

And its corresponding response:

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

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:

Subscribe for our updates

Please enter your email address and receive the latest updates.

Upwork leverages Nylas to enable users to hire twice as fast and boosts customer satisfaction

Salesloft partners with Nylas to power MS Exchange integration, unlocking new enterprise market

Everything you need to know about building, purchasing and integrating with APIs.

Elevating performance: Nylas’ commitment to enhancing our product