Only show these results:

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.

  1. 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"
}
  1. 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.

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's 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's 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": "kat@spacetech.com",
"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": "kat@spacetech.com",
"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:

  1. POST /connect/authorize
  2. POST /connect/token
  3. POST /calendars
  4. 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?