Create and list calendars

Before you can create or list events, you need a calendar ID. A user often has several calendars: a primary one, shared team calendars, and read-only subscriptions like holidays. Picking the right one, and knowing which you can write to, is the first step in any calendar integration.

The Nylas Calendar API lists every calendar on the account with one call and creates new ones with another, using the same shape across providers so you don’t special-case Google against Outlook.

How do I list a user’s calendars?

Send a GET /v3/grants/{grant_id}/calendars request. Nylas returns each calendar with an id, a name, and flags like is_primary, read_only, and is_owned_by_user. You need that id for every event call, so listing calendars is usually the first request your integration makes. It works across all 4 providers with one response shape, whether the account is Google, Microsoft, iCloud, or Exchange.

The request below lists the calendars on an account.

RequestResponse

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": {
    "grant_id": "1",
    "description": "<string>",
    "id": "2",
    "is_primary": false,
    "location": "<string>",
    "metadata": {
      "your-key": "<string>"
    },
    "name": "<string>",
    "object": "calendar",
    "read_only": false,
    "timezone": "UTC",
    "is_owned_by_user": false
  }
}

How do I create a calendar?

Send a POST /v3/grants/{grant_id}/calendars request with a name, plus optional description, location, and timezone. Creating calendars needs calendar write access and is supported on 2 providers: Google and Microsoft. The new calendar appears in the user’s account, and its returned id is what you pass to the events endpoints to create events on it.

Request

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

If you need a calendar for a room, a piece of equipment, or anything without its own account, use a virtual calendar instead, which works without a connected provider.

Things to know about calendars

A few flags on each calendar drive your logic. Most providers mark exactly 1 calendar as primary with the is_primary flag, a safe default when a user hasn’t picked one; iCloud is the exception, with no primary-calendar concept. The read_only flag matters most: shared and subscribed calendars are often read-only, and you can only create or edit events where read_only is false, so check it before you write across all 4 providers.

is_owned_by_user separates calendars the user owns from ones shared with them, which affects what they can edit. For the full calendar object, see using the Events API.

What’s next

• Find open meeting times across calendars using the calendar IDs you list
• Create Google events on a calendar you own
• Virtual calendars for rooms and resources without an account
• Update and delete calendar events once events exist on a calendar