{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiav7w5tbho6ihqutwllrvyl5dnximkafosixhkmfw7oy7v5aijuui",
    "uri": "at://did:plc:25rdn5elo5izoxrmtis34zuk/app.bsky.feed.post/3motdnm6bzxx2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreidbm3i63lnvfkfr6yqnrnmt2lyaqxvqifoaqjzneklgoysgveayze"
    },
    "mimeType": "image/webp",
    "size": 68952
  },
  "path": "/mqasimca/one-calendar-api-for-google-microsoft-and-beyond-nylas-calendar-46kk",
  "publishedAt": "2026-06-21T21:21:49.000Z",
  "site": "https://dev.to",
  "tags": [
    "calendar",
    "api",
    "devtools",
    "scheduling",
    "Nylas CLI",
    "Calendar API overview",
    "authentication docs",
    "GET /events",
    "calendar events list",
    "create event",
    "calendar events create",
    "send RSVP",
    "calendar events rsvp",
    "calendar availability check",
    "availability reference",
    "calendar find-time",
    "Create an event",
    "Availability API",
    "Nylas CLI command reference",
    "Qasim Muhammad",
    "Pouya Sanooei"
  ],
  "textContent": "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.\n\nThe 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.\n\nI work on the CLI, so the terminal snippets below are the commands I actually run when I'm poking at a calendar.\n\n##  Calendars, events, and the calendar_id\n\nA 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`.\n\nAn **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.\n\n##  Before you begin\n\nYou need a Nylas API key and a connected account with calendar scopes. The CLI gets you there in two commands:\n\n\n\n    nylas init        # create an account, generate an API key\n    nylas auth login  # connect an account over OAuth, store the grant\n\n\nAfter 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.\n\n##  List calendars and events\n\nStart by seeing what calendars the account has. The CLI lists them in one command:\n\n\n\n    nylas calendar list\n\n\nEach 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:\n\n\n\n    # Upcoming events on the primary calendar\n    nylas calendar events list\n\n    # Next 14 days, capped at 50 results\n    nylas calendar events list --days 14 --limit 50\n\n\nThe 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:\n\n\n\n    curl --request GET \\\n      --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&start=1718841600&end=1719446400\" \\\n      --header \"Authorization: Bearer <NYLAS_API_KEY>\"\n\n\nThe GET /events reference documents the full filter set — by calendar, time range, attendee, and more. The CLI equivalents are at calendar events list.\n\n##  Create an event with participants\n\nCreating 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):\n\n\n\n    nylas calendar events create \\\n      --title \"Design review\" \\\n      --start \"2026-06-23 14:00\" \\\n      --end \"2026-06-23 15:00\" \\\n      --participant alice@example.com \\\n      --participant bob@example.com \\\n      --location \"Zoom\"\n\n\nOver 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:\n\n\n\n    curl --request POST \\\n      --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary\" \\\n      --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n      --header \"Content-Type: application/json\" \\\n      --data '{\n        \"title\": \"Design review\",\n        \"when\": { \"start_time\": 1718901000, \"end_time\": 1718904600 },\n        \"participants\": [\n          { \"email\": \"alice@example.com\" },\n          { \"email\": \"bob@example.com\" }\n        ],\n        \"location\": \"Zoom\"\n      }'\n\n\nWhen 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.\n\n##  RSVP to invitations\n\nWhen 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.\n\nFrom the CLI:\n\n\n\n    nylas calendar events rsvp <event-id> yes --comment \"See you there\"\n\n\nOver HTTP, it's a `POST` to the event's send-rsvp endpoint with a `status`:\n\n\n\n    curl --request POST \\\n      --url \"https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>/send-rsvp?calendar_id=primary\" \\\n      --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n      --header \"Content-Type: application/json\" \\\n      --data '{ \"status\": \"maybe\" }'\n\n\nThere'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.\n\n##  Compute availability across calendars\n\nThis 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.\n\nThe endpoint is `POST /v3/calendars/availability`, and the four required fields are `participants`, `start_time`, `end_time`, and `duration_minutes`:\n\n\n\n    curl --request POST \\\n      --url \"https://api.us.nylas.com/v3/calendars/availability\" \\\n      --header \"Authorization: Bearer <NYLAS_API_KEY>\" \\\n      --header \"Content-Type: application/json\" \\\n      --data '{\n        \"start_time\": 1718841600,\n        \"end_time\": 1719446400,\n        \"duration_minutes\": 30,\n        \"participants\": [\n          { \"email\": \"alice@example.com\" },\n          { \"email\": \"bob@example.com\" }\n        ]\n      }'\n\n\nThe 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:\n\n\n\n    nylas calendar availability check \\\n      --emails alice@example.com,bob@example.com \\\n      --start \"tomorrow 9am\" \\\n      --end \"tomorrow 5pm\"\n\n\nThis 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.\n\n##  Find the best time, not just any time\n\nFree/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.\n\n\n\n    nylas calendar find-time \\\n      --participants alice@example.com,bob@example.com \\\n      --duration 1h \\\n      --days 7\n\n\nIt 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.\n\n##  Recurring events and limits\n\nRecurring 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`.\n\nDimension | Value | Notes\n---|---|---\nProviders | Google Calendar, Microsoft 365, and more | One event schema across all\nRSVP statuses |  `yes`, `no`, `maybe` | Microsoft Graph may not apply a \"no\" cleanly\nDefault calendar | `calendar_id=primary` | Resolves to the account's main calendar\nTime format | Unix timestamps | The `when` object holds `start_time` / `end_time`\nRecurrence | iCalendar `RRULE` | One event carries the whole series\n\nThe 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.\n\n##  Wrapping up\n\nCalendar 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.\n\nWhere to go next:\n\n  * Calendar API overview — calendars, events, and availability concepts\n  * Create an event and send RSVP — endpoint references\n  * Availability API — free/busy and group scheduling\n  * Nylas CLI command reference — every `nylas calendar` subcommand\n\n\n\n_Written by Qasim Muhammad and Pouya Sanooei._",
  "title": "One calendar API for Google, Microsoft, and beyond: Nylas Calendar"
}