How to Use Virtual Calendars

This guide will cover authenticating a virtual account using the Native Authentication workflow, creating a Virtual Calendar, and adding an event to the calendar.

Prerequisites

A Nylas account
Create a new application or use an existing application.
The Client ID from the application’s settings page.

Managing Virtual Calendars

To learn more about Virtual Calendars, see Virtual Calendars Overview.

Step 1: Authenticate the Account

Virtual Calendars use Native Authentication. Each time you need to create a new Virtual Account, you will need to follow this authentication process again.

Send a POST request to https://api.nylas.com/connect/authorize.

    curl --location --request POST 'https://api.nylas.com/connect/authorize' \
    --data-raw '{
    "client_id": "9df4ff17888f4729ad4e1463d2547d",
    "provider": "nylas",
    "scopes": "calendar", 
    "email": "virtual_account_unique_id",
    "name": "Virtual Calendar",
    "settings": {}
    }'

client_id - The Nylas App client ID. Required.
provider - nylas. The provider for Virtual Calendars must always be nylas . Required
scopes - calendar. Virtual Calendars only have access to the calendar scope. Required.
email - This can be any app-local unique string and is used to represent the email in requests to the calendar and events endpoints. Required
name - The name of your Virtual Calendar. Required
settings - This is passed in as an empty object. When making the POST request, this is required. Required

Email Field

The email field is a unique Virtual Account identifier. It can be anything as long as it is a unique string. Do not use an existing email address.

The request returns a code that is used in the second step of authentication.

    {
        "code": "HYL7zY1M1LpJ8iKAYKsx7RM1Wchz4b"
    }

Send a POST request to https://api.nylas.com/connect/token with the code from /connect/authorize.

    curl --location --request POST 'https://api.nylas.com/connect/token' \
    --data-raw '{
        "client_id": "9df4ff17888f4729ad4e1463d2547d",
        "client_secret": "dcc0bb54d8ae4c1ab95dc76694084b",
        "code": "HYL7zY1M1LpJ8iKAYKsx7RM1Wchz4b"
    }'

client_id - The application client ID. Required
client_secret - The application client secret. Required
code - The code response from /connect/authorize. Required

The response includes the access_token you need to authorize the account for API requests.

    {
        "access_token": "938134d41cf0465590b1cf0de1decd",
        "account_id": "dc41c2a1ce6840deba3cd41468fb75",
        "billing_state": "paid",
        "email_address": "virtual_account_unique_id",
        "id": "d38b60fb69ee40b3a11fa686c83987",
        "linked_at": 1598290473,
        "name": "Virtual Calendar Test",
        "object": "account",
        "organization_unit": "folder",
        "provider": "nylas",
        "sync_state": "running"
    }

The Virtual Calendar account shows as its own account in the Application Dashboard.

Learn More

Native Authentication.

Step 2: Create a Virtual Calendar

Now that you have a Virtual Calendar account, you can create a calendar for the account.

Authorization

The following API requests use the Bearer authorization method. Pass in your access token from the authentication step.

Send a POST request to https://api.nylas.com/calendars. The access_token will associate the calendar with the right account.

    curl --location --request POST 'https://api.nylas.com/calendars' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --data-raw '{
            "name":"Marie Radiation Services",
            "description":"Keep track of important customer appointments",
            "location":"Warsaw, Poland",
            "timezone":"Europe/Warsaw"
    }'

name - The name of the Virtual Calendar. Required
description - The description of the Virtual Calendar.
location - The geographic location of the calendar as a string.
timezone - IANA time zone database formatted string (e.g. America/New_York). If left blank no timezone is assigned to the calendar.

The response includes the calendar id needed to add events.

    {
        "account_id": "dc41c2a1ce6840deba3cd41468fb75",
        "description": "Keep track of important customer appointments",
        "id": "ac1046f1dd1746d6a979b53c973c56",
        "is_primary": null,
        "location": "Warsaw, Poland",
        "name": "Marie Radiation Services",
        "object": "calendar",
        "read_only": false,
        "timezone": "Europe/Warsaw"
    }

Learn More

Learn more about the Calendar API.

Step 3: Create an Event

Send a POST request to https://api.nylas.com/events.

    curl --location --request POST 'https://api.nylas.com/events' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --data-raw '{
        "title":"Good Flow Yoga",
        "when" : {
            "start_time": 1598281200,
            "end_time": 1598284800
        },
        "location": "Yoga Studio 5 Westlake",
        "calendar_id": "ac1046f1dd1746d6a979b53c973c56",
        "participants": [
            {
                "email": "[email protected]",
                "name": "Katherine Johnson"
            }
        ]
    }'

title - The title of the event.
when - The start and end time using Unix timestamp. Required
location - The event location. For example, a physical address or meeting room name.
calendar_id - The calendar ID for the event.
participants - The name and email of any participants.

The response is the final created event.

    {
        "account_id": "dc41c2a1ce6840deba3cd41468fb75",
        "busy": true,
        "calendar_id": "ac1046f1dd1746d6a979b53c973c56",
        "description": null,
        "ical_uid": null,
        "id": "dc41c2a1ce6840deba3cd41468fb75",
        "location": "Yoga Studio 5 Westlake",
        "message_id": null,
        "object": "event",
        "owner": "Virtual Calendar Test <virtual_calendar_email>",
        "participants": [
            {
                "comment": null,
                "email": "[email protected]",
                "name": "Katherine Johnson",
                "status": "noreply"
            }
        ],
        "read_only": false,
        "status": "confirmed",
        "title": "Good Flow Yoga",
        "when": {
            "end_time": 1598284800,
            "object": "timespan",
            "start_time": 1598281200
        }
    }

You created your first Virtual Calendar and event!

Learn More

Learn more about the Events API.

Summary

To create the Virtual Calendar you used:

POST /connect/authorize
POST /connect/token
POST /calendars
POST /events

Keep in Mind

Virtual Calendars use Native Authentication only.
Virtual Calendars support notifications.
Virtual Calendars only works with /account, /calendar, and /event endpoints.
Each Virtual Account is limited to one virtual calendar.

What's Next?

Virtual Calendars Overview