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.

{
  "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.

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.

Manage calendars from the terminal

The Nylas CLI lists and creates calendars from your terminal: nylas calendar list shows every calendar on the account with its ID, and nylas calendar create adds a new one with a name, timezone, and optional description, so you can set up shared or per-project calendars without opening the dashboard.

# List calendars with their IDs
nylas calendar list

# Create a calendar
nylas calendar create "Team events" --timezone America/New_York --description "Shared team calendar"

The same calendar list works across all 6 providers, and each calendar ID it returns is what you pass to event commands like events list and events create. The CLI also has calendar update and calendar delete for the full lifecycle. See the calendar list command reference.

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