标签：#calendar

"What time works for everyone?" is a surprisingly hard question to answer in code. You have to read each person's calendar, line up the busy blocks, respect working hours and time zones, leave buffer time between meetings, and only then find the gaps everyone shares. The Nylas Availability API does all of that in one request: hand it a list of participants and a window, and it returns the time slots that actually work. This post covers finding meeting times from two angles: the HTTP API for your backend, and the nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm checking a calendar. Availability versus Free/Busy There are two endpoints here, and picking the right one saves you work. The Availability endpoint finds bookable slots across a group of participants, applying working hours, buffers, and meeting duration to return times you can actually book. Free/Busy is simpler: it returns the raw busy blocks for one or more email addresses over a window, leaving the slot math to you. Reach for Availability when the question is "when can these people meet?" and you want the answer as a list of open slots. Reach for Free/Busy when you only need to see when calendars are busy, for example to gray out times in a custom UI. Availability is a POST /v3/calendars/availability , an application-level call that takes participants by email, while Free/Busy is grant-scoped at POST /v3/grants/{grant_id}/calendars/free-busy . This post focuses on Availability, since that's the one that answers the scheduling question directly. Find a time across participants The core request lists the participants and the window to search. Each participant is identified by email and must be associated with a valid Nylas grant, since the endpoint reads their calendars. You set start_time and end_time as Unix timestamps for the search window, duration_minutes for how long the meeting is, and interval_minutes for how the candidate start times ar

An AI agent that can email but can't hold a calendar slot is only half useful. The moment a conversation turns into "let's meet Thursday at 2," the agent needs a real calendar — one that sends invitations people accept in Google Calendar or Outlook, receives invites at its own address, and RSVPs back so the organizer sees a real response next to everyone else's. Bolting a scheduling library onto a shared mailbox doesn't get you there; the agent needs a calendar identity of its own. An Agent Account ships with exactly that. Every account gets a primary calendar that hosts events, accepts invitations over standard iCalendar, and RSVPs with yes, no, or maybe. To a participant, the agent is just another attendee on the invite. This post walks through using that calendar from two angles: the HTTP API for your backend, and the Nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for. The calendar an Agent Account comes with When Nylas provisions an Agent Account, it creates a primary calendar that belongs to the account. You reach it through the same Calendars and Events endpoints at /v3/grants/{grant_id}/... that any other grant uses, so calendar code you've written for a connected Google or Microsoft account works here unchanged. Each account gets: A primary calendar , provisioned automatically. It can't be deleted while other calendars exist on the account. Additional calendars , up to your plan's cap, for separating concerns — a sales-calls calendar and an internal one on the same agent. Free/busy queries , so the agent can check its own availability before proposing a time. Event webhooks — event.created , event.updated , and event.deleted fire on every change, whether it came from the agent or from someone responding to an invitation. List the calendars from the terminal with nylas calendar list , or over the API with GET /v3/grants/{grant_id}/calendars . Both return the primary calendar plus any you've added. List what'

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

A human assistant borrows the boss's calendar; a scheduling bot owns its own. That one difference dissolves most of what makes calendar automation miserable. The borrowed-calendar model is how nearly every scheduling tool works today: connect to a person's Google or Microsoft account via OAuth, request calendar scopes, and act on their behalf. It works, but the seams show everywhere. The human's calendar fills with bookings the bot manages. Delegation permissions vary by provider and admin policy. Tokens expire when the person changes their password or leaves the company. And the bot has no address of its own — every invite, every confirmation email, appears to come from a person who didn't write it. Nylas Agent Accounts (currently in beta) invert this. Each account is a real mailbox and a real calendar , provisioned automatically, owned by your application. From a participant's perspective there's nothing special about it — it's just another attendee on the invite. What "owning availability" actually changes When the bot's calendar is its own, availability stops being a permissions question and becomes a query. The agent calls the free/busy endpoint against its own primary calendar, gets back busy blocks for a time window, and proposes open slots. No delegation, no scopes negotiation, no "the admin needs to approve calendar sharing for service accounts." The scheduling-agent tutorial wires the whole loop: a meeting request lands at scheduling@agents.yourcompany.com , a message.created webhook fires, an LLM parses duration and timezone, the agent checks its own free/busy and replies with 3 candidate slots. When the human picks one, the agent creates the event: curl --request POST \ --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&notify_participants=true" \ --header "Authorization: Bearer <NYLAS_API_KEY>" \ --header "Content-Type: application/json" \ --data '{ "title": "Product demo", "when": { "start_time": 1744387200, "end_time": 174

NYT reported Kennedy is disengaged. Kennedy's response seems to show NYT is right.

A scheduling link makes the human do the work; a scheduling agent with its own calendar does the negotiating. Booking pages outsource the back-and-forth to a UI. The agent model keeps it where it already happens — in email — and answers from a real address with a real calendar behind it. The setup: meeting requests land at scheduling@agents.yourcompany.com , an LLM parses intent, the agent checks availability against its own free/busy, proposes slots, and creates events that show up as normal invitations in Google Calendar, Microsoft 365, and Apple Calendar. No human mailbox in the loop, no delegation permissions, no calendar borrowed from whoever set the bot up. This runs on a Nylas Agent Account — a hosted mailbox-plus-calendar you provision through the API. Agent Accounts are in beta, so expect some movement before GA. Provision the identity One CLI command or one API call: nylas agent account create scheduling@agents.yourcompany.com The primary calendar is provisioned automatically — no extra call before you can create events on it. The API equivalent is POST /v3/connect/custom with "provider": "nylas" and the email address in settings ; no OAuth refresh token involved. Save the grant ID, then subscribe a webhook to four triggers: message.created , event.created , event.updated , and event.deleted . When Nylas sends the challenge GET to your endpoint, respond with the challenge value within 10 seconds to activate it. The negotiation loop The full tutorial wires this end to end, but the shape is: Human emails the agent. message.created fires; the webhook only carries summary fields, so the handler fetches the full body. The LLM extracts duration, timezone, and urgency. The agent queries /calendars/free-busy against its own primary calendar and replies with 3 candidate slots. The human picks one; another message.created fires; the agent creates the event with notify_participants=true . The availability check is the part people overcomplicate. Free/busy returns bus