Using the v2 Calendar API

The Nylas Calendar API is the simplest way to access calendar and event data for users across multiple providers. This guide introduces the basic functionality of the Nylas Calendar API using curl and other examples. See Using the Events API for information about creating and modifying the events that a calendar contains.

Most examples also include the JSON response, so you don't have to make a query on your own to see the expected response structure.

The examples in this page cover how to use the Nylas Calendar API for the following actions:

Get a list of available calendars.
Get calendars.
Create calendars.
Update calendars.

Calendars and Events

In general, a Calendar object serves as a container for Event objects. A single connected account usually has access to several calendars, but one is always considered the "primary" or default calendar for that user. Calendars can be shared among users, and users might have full read/write access to a calendar (owner or organizer), read-only access (subscriber), or be able to see free/busy information only.

Event objects are containers for information about scheduled events. This includes a list of the people involved, details about the time, meeting location (in-person address or virtual conferencing details), and a description. They can also include attachments and information about who has confirmed their attendance.

Nylas includes APIs to get user availability, as well as read and modify calendars.

Types of calendars

All calendar users have a main or "primary" calendar associated with their account, and you can refer to this in API requests either as primary, by its calendar_id, and sometimes by the account's email address.

In addition to the primary calendar, all accounts with email scopes also include a special calendar called "Emailed events". This calendar contains event invitations that were sent to the user's mailbox. This calendar is read-only, because it is compiled from email data. This means emailed-events can't be added, updated, or deleted.

A user account might also contain additional private calendars belonging to the user, read-only calendars, shared or group calendars, the calendars of individual colleagues, and bookable resources like rooms, equipment, and conference lines.

If you need to refer to these calendars, use the GET /calendars request to return a list, and use the ID returned with the calendar you want to use.

Provider calendars

There are several types of provider calendars: personal, group, and resource calendars. Users can view, add, modify, and delete Events on calendars where read_only is false. Nylas automatically syncs any changes back to the provider.

Most individual accounts have a "primary" or default calendar, usually identified using the account's name or email address, or sometimes just named "Calendar."

Users can also have other custom calendars, access to colleagues' calendars, access to shared team calendars, or calendars for resources like conference rooms or equipment. See the documentation on Events for more details.

Limited calendar support for IMAP providers

IMAP is a protocol for receiving email only. "IMAP" service providers use the IMAP protocol to receive mail, and the SMTP protocol to send it. Neither of these protocols includes calendar functionality. You are only able to read the Emailed Events calendar (described below) for IMAP providers.

Emailed Events calendars

All accounts also include a special calendar called "Emailed Events" which contains event invitations that were sent to the user's mailbox. This calendar is read-only, because it is compiled from email data. This means emailed-events can't be added, updated, or deleted.

The Emailed Events calendar can receive RSVPs. See the Events reference documentation for more details.

Virtual calendars

You can use virtual calendars when you need to schedule people or objects that don't have an associated calendar, for example a consultant who doesn't have an email address at your company, or a room resource that only needs a calendar and doesn't have an associated email address.

See the Virtual calendars documentation to learn more.

Calendar availability

The Nylas APIs include multiple ways to get user availability so you can book meetings or run other time-based operations.

Free-Busy data

The simplest version of this is the Free/Busy endpoint. This endpoint queries the provider, which returns simple information about about blocks of time when the user is booked and not available. If you're querying a user within your organization, this information is usually public within the org. If you're querying for a user outside your organization, the calendar's owner must have published or made public the free/busy data.

Availability

You can use the Availability endpoint to find space in a user's calendar for a meeting with specific and detailed criteria. Use the endpoint to find a time that works, which you can then feed to the Events API to create an actual booking.

Before you begin

To follow along with the samples on this page, you first need to sign up for a Nylas developer account. This gets you a free Nylas application and an API key.

Get available calendars

⚠️ It can take up to one minute to sync calendars after you connect an account. If you make a GET /calendars request before calendars are synced, Nylas returns an empty array.

Most user accounts subscribe to multiple calendars. To view a list of all calendars the user has access to, make a Get Calendars request.

While going through this guide, copy the id of a calendar that you are willing to make modifications to. You can always create a new calendar for this purpose if you don't want to test features out on any of your existing calendars.

This guide uses a query parameter to limit the number of results to five to make examples easier to read. See the pagination documentation to learn more about controlling the number of objects that are returned. The calendars endpoint also supports views to further customize Nylas' response.

The following example shows how to get an end user's available calendars with a GET /calendars request and an example of the JSON response you can expect.

Request
Response (JSON)

curl -X GET https://api.nylas.com/calendars?limit=5

[
  {
    "account_id": "joujhadwh59pz9rvfjfw",
    "description": "Emailed events",
    "id": "zd08j9stfph95u449vti",
    "name": "Emailed events",
    "object": "calendar",
    "read_only": true
  },
  {
    "account_id": "joujhadwh59pz9rvfjfw",
    "description": null,
    "id": "a6jx8278v11s53itpdcn",
    "name": "jane.doe@example.com",
    "object": "calendar",
    "read_only": false
  }
]

You can also get a list of the user's available calendars using the Nylas SDKs.

v2 Node.js SDK
v2 Python SDK
v2 Ruby SDK
v2 Java SDK

const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.calendars.list({limit: 5}).then(calendars => console.log(calendars));

from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

print(nylas.calendars.where(limit=5))

require 'nylas'

nylas = Nylas::API.new(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

calendars = nylas.calendars.limit(5)
calendars.each{ |calendar|
    puts calendar.inspect
}

import java.io.IOException;
import com.nylas.*;

public class ReadCalendars {
  public static void main(String[] args) throws RequestFailedException, IOException {
    NylasClient client = new NylasClient();
    NylasAccount account = client.account("ACCESS_TOKEN");

    RemoteCollection<Calendar> calendar_list = account.calendars().
        list(new CalendarQuery().
        limit(5));

    for (Calendar calendar : calendar_list){
      System.out.println(calendar);
    }
  }
}

To learn more about the values that the /calendars endpoint returns, see the v2 Calendar API documentation.

Get a calendar

You can return information about a single calendar by making a Get Calendar request that includes the appropriate calendar id.

The following example shows how to get details for a specific calendar with a GET /calendars/{id} request and an example of the JSON response you can expect.

Request
Response (JSON)

curl -X GET https://api.nylas.com/calendars/<CALENDAR_ID>

{
  "account_id": "joujhadwh59pz9rvfjfw",
  "description": "Emailed events",
  "id": "zd08j9stfph95u449vti",
  "name": "Emailed events",
  "object": "calendar",
  "read_only": true
}

You can also get a specific calendar using the Nylas SDKs, as in the examples below.

v2 Python SDK
v2 Ruby SDK
v2 Java SDK
v2 Node.js SDK

from nylas import APIClient

nylas = APIClient(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

print(nylas.calendars.get('{id}'))

require 'nylas'

nylas = Nylas::API.new(
    APP_ID,
    APP_SECRET,
    ACCESS_TOKEN
)

calendar = nylas.calendars.find("{id}")

puts calendar.inspect

import java.io.IOException;
import com.nylas.*;

public class ReadCalendars {
  public static void main(String[] args) throws RequestFailedException, IOException {
    NylasClient client = new NylasClient();
    NylasAccount account = client.account("ACCESS_TOKEN");
    Calendar calendar = account.calendars().get("{ID}");

    System.out.println(calendar);
  }
}

const Nylas = require('nylas');

Nylas.config({
  clientId: NYLAS_CLIENT_ID,
  clientSecret: NYLAS_CLIENT_SECRET,
});

const nylas = Nylas.with(ACCESS_TOKEN);

nylas.calendars.find('{id}').then(calendar => console.log(calendar));

Create a calendar

Because a calendar is a container for Event objects, it doesn't have a lot of parameters or options available. In fact, when creating a calendar for a Microsoft account, you can only specify the name as a string. For other providers, you can also add a description, a location description, a timezone in IANA time zone format, and optional metadata.

It might take a while for the new calendar to be created on the provider. You can use the v2 Job Status endpoint to monitor the sync-back process.

The following example shows how to create a calendar with a POST /calendars request.

curl --request POST \
  --url https://api.nylas.com/calendars \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My New Calendar",
  "description": "Description of my new calendar",
  "location": "Location description",
  "timezone": "America/Los_Angeles",
  "metadata": {
    "event-type": "gathering"
  }
}'

You can also use the Nylas SDKs to create a calendar.

v2 Node.js SDK
v2 Python SDK
v2 Ruby SDK
v2 Java SDK

const Nylas = require('nylas');
Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

const calendar = new Calendar(nylas, {
  name: "My New Calendar",
  description: "Description of my new calendar",
  location: "Location description",
  timezone: "America/Los_Angeles",
  metadata: {
    test: "true",
  }
})

calendar.save();

from nylas import APIClient

nylas = APIClient(
  NYLAS_CLIENT_ID,
  NYLAS_CLIENT_SECRET,
  ACCESS_TOKEN
)

calendar = nylas.calendars.create()
calendar.name = "My New Calendar"
calendar.description = "Description of my new calendar"
calendar.location = "Location description"
calendar.timezone = "America/Los_Angeles"

calendar.save()

## Create a calendar

api.calendars.create(
  name: "My New Calendar",
  description: "Description of my new calendar",
  location: "Location description",
  timezone: "America/Los_Angeles",
  metadata: {
    event_type: "gathering"
  }
)

NylasClient nylas = new NylasClient();
NylasAccount account = nylas.account("{ACCESS_TOKEN}");
Calendars calendars = account.calendars();

Calendar newCal = new Calendar();
newCal.setName("New Test Calendar");
newCal.setDescription("Testing calendar creation");
newCal.setLocation("far, far away");
newCal.setTimezone("America/Los_Angeles");

Calendar created = calendars.create(newCal);

// Add Metadata

Calendar newCal = new Calendar();
newCal.setName("New Test Calendar");
newCal.setDescription("Testing calendar creation");
newCal.setLocation("far, far away");
newCal.setTimezone("America/Los_Angeles");

Map<String, String> metadata = new HashMap<>();
metadata.put("calendar_type", "test");
newCal.setMetadata(metadata);

Calendar created = calendars.create(newCal);

Update a calendar

You can update a calendar to change any of the available fields, except if the provider is Microsoft. You can update only the name string of a Microsoft calendar. To update any other information, you must delete the calendar and re-create it.

To update a calendar in Nylas v2, make a PUT /calendars/{id} request, similar to the example below.

curl --request PUT \
  --url https://api.nylas.com/calendars/<CALENDAR_ID> \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My New Calendar",
  "description": "Description of my new calendar",
  "location": "Location description",
  "timezone": "America/Los_Angeles"
}'

You can also update a calendar using the Nylas SDKs.

v2 Node.js SDK
v2 Python SDK
v2 Ruby SDK
v2 Java SDK

const Nylas = require('nylas');
Nylas.config({clientId: 'clientId', clientSecret: 'clientSecret'});
const nylas = Nylas.with('access_token');

const calendar = await nylas.calendars.find('{id}');
calendar.name = "Updated Calendar Name";
calendar.metadata = {
  test: "true",
};
calendar.save();

from nylas import APIClient

nylas = APIClient(
  NYLAS_CLIENT_ID,
  NYLAS_CLIENT_SECRET,
  ACCESS_TOKEN
)

calendar = nylas.calendars.get('{id}')
calendar.name = "Updated Calendar Name"
calendar.save()

# Or you can update a calendar with metadata

calendar = api.calendars.last

calendar.update(metadata: {
  test: "true",
}};

NylasClient nylas = new NylasClient();
NylasAccount account = nylas.account("{ACCESS_TOKEN}");
Calendars calendars = account.calendars();

// Get a calendar by specifying the calendar ID
Calendar calendar = calendars.get("CALENDAR_ID");

calendar.setName("New Test Calendar (changed)");
calendar.setDescription("this calendar has been updated!");
calendar.setLocation("nearby");
calendar.setTimezone("America/New_York");

Calendar updated = calendars.update(created);

// Metadata

Map<String, String> metadata = new HashMap<>();
metadata.put("calendar_type", "test");
calendar.setMetadata(metadata);
Calendar updatedCalendar = account.calendars().update(calendar);