DEV Community

Qasim
Qasim

Posted on

One calendar API for Google, Microsoft, and beyond: Nylas Calendar

#calendar #api #devtools #scheduling

Scheduling features look simple until you build them. Google Calendar speaks its own REST API with events.insert; Microsoft 365 wants Graph and POST /me/calendar/events; Apple and a long tail of providers expect CalDAV. The moment your app needs to read a user's events, drop a meeting on their calendar, or check whether three people are free at 2pm, you're staring down three integrations that disagree on field names, time formats, and recurrence rules.

The Nylas Calendar API gives you one interface over all of them. Connect a user's account once, get a grant_id, and read calendars, manage events, send RSVPs, and compute free/busy with the same request shape whether the backing provider is Google or Microsoft. This post walks the calendar surface from both sides: the HTTP API your backend calls, and the Nylas CLI for testing the same operations in a terminal.

I work on the CLI, so the terminal snippets below are the commands I actually run when I'm poking at a calendar.

Calendars, events, and the calendar_id

A connected account has one or more calendars, and every event belongs to exactly one of them. Most operations take a calendar_id, and the special value primary resolves to the account's default calendar — so you don't need to look up an ID to act on the main calendar. One exception: iCloud doesn't support primary, so for iCloud accounts you pass a real calendar ID from nylas calendar list.

An event carries a title, a when object holding its start and end times, a list of participants, an optional location, and flags like busy. That schema is identical across providers, which is the whole point: you read a Google event and a Microsoft event into the same struct. See the Calendar API overview for how calendars, events, and availability fit together.

Before you begin

You need a Nylas API key and a connected account with calendar scopes. The CLI gets you there in two commands:

nylas init        # create an account, generate an API key
nylas auth login  # connect an account over OAuth, store the grant
Enter fullscreen mode Exit fullscreen mode

After login the CLI uses that grant as your default, so the nylas calendar commands below run without an explicit ID. For the production OAuth flow and the calendar scopes Google and Microsoft require, see the authentication docs.

List calendars and events

Start by seeing what calendars the account has. The CLI lists them in one command:

nylas calendar list
Enter fullscreen mode Exit fullscreen mode

Each row includes the calendar ID you'll pass to event operations. To list events, point at a calendar and a time window. The CLI defaults to the primary calendar and a short look-ahead:

# Upcoming events on the primary calendar
nylas calendar events list

# Next 14 days, capped at 50 results
nylas calendar events list --days 14 --limit 50
Enter fullscreen mode Exit fullscreen mode

The same read over HTTP is a GET against the events collection, and calendar_id is a required query parameter. Pass start and end as Unix timestamps to bound the window:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&start=1718841600&end=1719446400" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

The GET /events reference documents the full filter set — by calendar, time range, attendee, and more. The CLI equivalents are at calendar events list.

Create an event with participants

Creating an event is a single POST. The only strictly required pieces are the calendar_id query parameter and a when object in the body — title and participants are optional, though you'll almost always set them. The CLI's events create takes start and end times in YYYY-MM-DD HH:MM form (or a bare YYYY-MM-DD for an all-day event):

nylas calendar events create \
  --title "Design review" \
  --start "2026-06-23 14:00" \
  --end "2026-06-23 15:00" \
  --participant alice@example.com \
  --participant bob@example.com \
  --location "Zoom"
Enter fullscreen mode Exit fullscreen mode

Over HTTP, the when object has a few shapes; the one used here is a timespan that takes start_time and end_time as Unix timestamps (the others are a single time, a date, and a datespan). Each participant is an object with an email:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Design review",
    "when": { "start_time": 1718901000, "end_time": 1718904600 },
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ],
    "location": "Zoom"
  }'
Enter fullscreen mode Exit fullscreen mode

When you add participants, the provider sends them invitations and they show up as normal calendar invites in Gmail, Outlook, or Apple Calendar. One field worth knowing is conferencing: set it and Nylas can auto-create a video link (Google Meet, Teams, or Zoom depending on the provider) so you don't have to mint one yourself. The full request body — busy, recurrence, conferencing, metadata — is in the create event reference, and the CLI flags are at calendar events create.

RSVP to invitations

When the connected account is invited to an event, you can respond programmatically. The RSVP status is one of exactly three values — yes, no, or maybe — and Nylas sends it to the event organizer as an email update, the same notification you'd trigger by clicking the button in a mail client.

From the CLI:

nylas calendar events rsvp <event-id> yes --comment "See you there"
Enter fullscreen mode Exit fullscreen mode

Over HTTP, it's a POST to the event's send-rsvp endpoint with a status:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=primary" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "status": "maybe" }'
Enter fullscreen mode Exit fullscreen mode

There's a provider quirk worth flagging here, straight from the API docs: due to a Microsoft Graph limitation, declining ("no") might not update the event status properly on Microsoft accounts — the event stays on the calendar with the no-RSVP status rather than being removed. If your app relies on RSVP state for Microsoft users, test that path explicitly. The send RSVP reference and the calendar events rsvp command document the rest.

Compute availability across calendars

This is the operation that's genuinely painful to build yourself, because it means reading several people's free/busy data from potentially different providers and intersecting it. The Calendar API does the intersection for you. POST /availability takes a list of participants, a time range, and a meeting duration, and returns only the slots when everyone is free.

The endpoint is POST /v3/calendars/availability, and the four required fields are participants, start_time, end_time, and duration_minutes:

curl --request POST \
  --url "https://api.us.nylas.com/v3/calendars/availability" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "start_time": 1718841600,
    "end_time": 1719446400,
    "duration_minutes": 30,
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

The response is the set of 30-minute windows where all participants are free across the whole range. The CLI exposes the same computation through calendar availability check:

nylas calendar availability check \
  --emails alice@example.com,bob@example.com \
  --start "tomorrow 9am" \
  --end "tomorrow 5pm"
Enter fullscreen mode Exit fullscreen mode

This single endpoint replaces the read-everyone, normalize-timezones, intersect-the-gaps logic you'd otherwise write by hand. The availability reference covers group availability, round-robin, and open-hours constraints.

Find the best time, not just any time

Free/busy tells you when people can meet. It doesn't tell you when they should. A slot at 7am for someone in Berlin and 10pm for someone in Tokyo is technically "free" but a terrible choice. The CLI's find-time command layers a scoring model on top of availability to rank candidate slots.

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --duration 1h \
  --days 7
Enter fullscreen mode Exit fullscreen mode

It scores each candidate out of 100 points across five factors: working hours (40 points — is everyone inside 9-to-5?), time quality (25 points — morning versus late afternoon), cultural norms (15 points — avoid Friday afternoons and the lunch hour), weekday preference (10 points — mid-week beats Monday), and holiday avoidance (10 points). You can override the working window with --working-start and --working-end and pass per-participant timezones with --timezones. Full flags are at calendar find-time.

Recurring events and limits

Recurring events use the standard iCalendar RRULE format in the event's recurrence field, so a weekly standup is one event with a recurrence rule rather than 52 separate events. The CLI groups recurring-event operations under nylas calendar recurring.

Dimension Value Notes
Providers Google Calendar, Microsoft 365, and more One event schema across all
RSVP statuses yes, no, maybe Microsoft Graph may not apply a "no" cleanly
Default calendar calendar_id=primary Resolves to the account's main calendar
Time format Unix timestamps The when object holds start_time / end_time
Recurrence iCalendar RRULE One event carries the whole series

The provider differences that survive the abstraction are narrow: the Microsoft RSVP quirk above, and the fact that auto-conferencing creates a Meet link on Google and a Teams link on Microsoft. Everything else — reading events, creating them, computing availability — is one code path.

Wrapping up

Calendar work is where provider fragmentation hurts most, because availability and invitations genuinely require reading and writing across accounts. Doing it once through one schema, instead of once per provider, is the difference between a feature you ship this week and one you maintain forever. The CLI mirrors every operation, so you can prove out a scheduling flow in the terminal before writing a line of backend code.

Where to go next:

Written by Qasim Muhammad and Pouya Sanooei.

Top comments (0)