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's already on the calendar

Before the agent creates or responds to anything, it usually needs to see what's already scheduled. GET /v3/grants/{grant_id}/events lists events on a calendar, and passing expand_recurring=true materializes each instance of a recurring series instead of returning the single recurrence rule — which matters when the agent is checking specific days, not the pattern. For a one-shot sync across a window, GET /v3/grants/{grant_id}/events/import pulls events across the account's calendars over a time range.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&expand_recurring=true" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

From the terminal, nylas calendar events list shows the upcoming events and nylas calendar events show <event-id> prints a single one with its participants and current RSVP statuses. This is the read side the agent leans on before deciding whether a new request even fits.

Host an event and invite people

When the agent creates an event with participants and notify_participants=true, an invitation goes out from the Agent Account's address, and each participant sees the same thing they'd see for an invite from a colleague. A Google Calendar user gets it in Gmail, clicks Yes, and Google sends the response back automatically; an Outlook user clicks Accept and Microsoft does the same. Each response updates the event's participants[].status, and an event.updated webhook fires so the agent knows who accepted without parsing any mail.

Over the API, that's a POST to the events collection with notify_participants=true:

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": 1744390800 },
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ]
  }'

The CLI builds the same invite without hand-writing JSON. nylas calendar events create takes the title, start and end times, and one --participant flag per attendee:

nylas calendar events create \
  --title "Product demo" \
  --start "2025-04-11T16:00:00Z" \
  --end "2025-04-11T17:00:00Z" \
  --participant alice@example.com \
  --participant bob@example.com

Times live on the event itself. Pass epoch start_time and end_time over the API, or ISO 8601 timestamps to the CLI's --start and --end, with an optional --timezone. The Agent Account has no default time zone the way a human user's calendar does, so always be explicit about when the event happens.

Update and cancel without breaking the invite

A change to a hosted event has to reach everyone who already has it on their calendar, and Nylas handles that through the same iCalendar machinery as the original invite. When the agent is the organizer, PUT /v3/grants/{grant_id}/events/{event_id} pushes a time, title, or location change to every participant's calendar, and DELETE sends a cancellation that removes the meeting from their calendars. From the CLI, those are nylas calendar events update and nylas calendar events delete.

Set notify_participants deliberately on every change. With it true, each create, update, and delete sends email, which is usually what you want. Pass false to make a silent change — pre-staging an event the agent will announce later, or backfilling history without pinging anyone. One trap worth calling out: deleting an event without notification leaves the meeting sitting on participants' calendars, so cancel with notification unless you have a reason not to.

Receive invitations sent to the agent

The agent doesn't only host meetings; people invite it to theirs. When someone adds the Agent Account's address as a participant on their event, their calendar sends the invitation to the agent's mailbox, Nylas parses it, and a matching event appears on the agent's primary calendar with an event.created webhook. The agent is listed as a participant with status: "noreply", and the organizer is whoever sent the invite.

This is the part that makes the calendar genuinely useful for automation. You can drive the agent's response logic entirely off the event.created webhook without ever opening the invitation email — the event object already carries the organizer, participants, times, and description the agent needs to decide whether to attend. The invite also arrives as a normal message, so message.created fires alongside event.created; pick the event webhook to drive scheduling logic and ignore the mail copy.

RSVP so the organizer sees a real response

When the agent decides on an invitation, it responds with POST /v3/grants/{grant_id}/events/{event_id}/send-rsvp and a status of yes, no, or maybe. This is the correct way for the agent to reply — a plain email back to the organizer won't update their calendar, but a send-rsvp sends an iCalendar reply that does.

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": "yes" }'

From the terminal, nylas calendar events rsvp takes the event ID and the status as positional arguments, with an optional --comment that rides along with the reply:

# Accept an invitation
nylas calendar events rsvp <event-id> yes

# Decline with a note
nylas calendar events rsvp <event-id> no --comment "I have a conflict"

From the organizer's side, the agent's response appears in their calendar exactly like any attendee's — accepted, declined, or tentative next to every other participant — and other attendees see it too, because their calendars get the update automatically. After the call, an event.updated webhook fires on the agent's own calendar so it sees its own state change.

Check availability before proposing a time

Before the agent proposes a slot, it should know when it's actually free. The free/busy endpoint returns busy blocks for the Agent Account's primary calendar over a time window, which is what you'd query to avoid double-booking the agent. Over the API, that's POST /v3/grants/{grant_id}/calendars/free-busy with a start and end time and the Agent Account's email address:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/calendars/free-busy" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "start_time": 1744387200,
    "end_time": 1744473600,
    "emails": ["agent@agents.yourcompany.com"]
  }'

When the agent juggles more than one calendar, POST /v3/grants/{grant_id}/calendars/availability goes a step further than free/busy: it returns open windows across the account's calendars over a time window, so you get candidate slots rather than raw busy blocks. From the CLI, use nylas calendar availability check or nylas calendar find-time to check candidate slots. Either way, the point is the same: query the agent's own calendar first, then create the event for a time you know is open.

When the agent needs to negotiate a time

Counter-proposing a different time isn't a first-class operation. If the proposed slot doesn't work, the common pattern is to RSVP with no or maybe, then reply to the invitation with an alternative and let the organizer create a new event. For an agent driving the negotiation itself, query free/busy, propose a slot the agent is open for, and create the event once the other side agrees.

One limit to know before you reach for Scheduler, the Nylas product built for round-trip booking: its endpoints (/v3/scheduling/*) aren't available for Agent Account grants yet, per the supported-endpoints reference. So for an Agent Account today, time negotiation runs through the Events API and your own logic — propose, RSVP, and create — rather than a hosted scheduling page. When you already know the time, the Events API is all you need.

Things to keep in mind

A few behaviors are specific to running a calendar through an agent, where automation reacts to things a human would handle by reflex. None are complicated, but each one prevents a visible scheduling bug.

• An Agent Account is always a real mailbox too. Every inbound invite fires both event.created and message.created. Decide which one drives the agent's logic — the event webhook — and ignore the other.
• Invitations count toward the send quota. Every create, update, and delete with notify_participants=true sends email, and each counts against the account's daily send quota — 200 messages a day on the free plan. Over quota, the event still saves but the invitation is skipped silently, so no one is notified.
• Cancel with notification. Deleting an event without notify_participants=true leaves it on participants' calendars. Use notification unless you mean to remove it quietly.
• Be explicit about time. Pass epoch start_time/end_time or a timezone — the agent has no default zone, so an ambiguous time lands wherever the server guesses.
• send-rsvp is the only RSVP that counts. A reply email to the organizer won't move their calendar. Use the endpoint so the response propagates to every participant.

Wrapping up

A calendar turns an agent from something that talks about meetings into something that books them. The agent hosts events that real people accept, takes invitations at its own address, and RSVPs in a way every calendar respects — all through the same Events API you'd use for a connected account, plus the CLI for testing it by hand. The two habits that keep it clean: drive logic off the event webhooks, and set notify_participants on purpose every time.

Where to go next:

• How Agent Account calendars work — the full guide to hosting, receiving, and RSVPing
• Events API reference — request and response schemas for create, update, delete, and send-rsvp
• Supported endpoints — every calendar and event endpoint that works with Agent Account grants
• Scheduler — the Nylas hosted scheduling tool, not yet available for Agent Account grants