Build for free

A small guide to Virtual Calendars

Mar 21, 2023 • 6 min read

Jump to section

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": "[email protected]",
                "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:

Related resources

What to do when there’s no email admin

Nylas’ security & compliance program for communication APIs

How Foundersuite Helped 100,000+ Startups Raise $21 Billion With Better Email Capabilities

The State of Agentic AI in 2026: What teams are actually shipping