An RSVP can carry exactly three values: yes
, no
, or maybe
. That tiny vocabulary — plus a 30-year-old text format called iCalendar — is the entire reason a calendar owned by an AI agent can host meetings that real people accept in Google Calendar, Microsoft 365, and Apple Calendar without any of those clients knowing (or caring) that the other participant is software.
Nylas Agent Accounts — programmatic mailboxes currently in beta — each ship with a real calendar. There's no Google integration, no Microsoft Graph adapter, no per-provider code. The interop happens at the protocol layer, and it's worth understanding how.
When an Agent Account creates an event, the invitation goes out as an ICS REQUEST
. When it cancels one, participants get an ICS CANCEL
. When it responds to an invite, the organizer receives an ICS REPLY
. Every major calendar client already speaks this dialect, which is why an agent's events look native everywhere: there's nothing to translate.
That's the whole trick. Calendar interop isn't an API problem; it's an email problem. Invitations, updates, and responses travel as messages between mailboxes, and since every Agent Account is a real mailbox with a primary calendar attached, it participates in that exchange like any colleague would.
Create an event with notify_participants=true
and each participant gets an invitation from the agent's own email address:
curl --request POST \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary¬ify_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" }
]
}'
From here, the providers do the heavy lifting. A Google Calendar user sees the invite in Gmail and clicks Yes; Google sends the response back to the agent's mailbox automatically. Outlook and Apple Calendar behave the same way with Accept/** Decline**/** Tentative**. Each response lands in the agent's inbox, gets parsed, and the event's participants[].status
updates on its own. An event.updated
webhook fires, so your agent learns who accepted without ever reading the email.
Updates and deletes follow the same path: PUT /events/{id}
pushes the change to every participant's calendar, and DELETE /events/{id}
sends the cancellation — as long as notify_participants=true
. A reschedule looks like this:
curl --request PUT \
--url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>?calendar_id=primary¬ify_participants=true" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"when": { "start_time": 1744390800, "end_time": 1744394400 }
}'
The new time shows up on Alice's and Bob's calendars wherever they're looking at them — no re-invite, no manual acceptance dance for a simple time change.
Pass notify_participants=false
when you want silent changes, like pre-staging events the agent will announce later, or backfilling historical data without spamming anyone. But be careful with deletes: cancelling an event without notification leaves the meeting sitting on every participant's calendar, and they'll show up to a meeting the agent no longer knows about. Delete with notification unless you have a specific reason not to.
The reverse direction needs zero code. Someone adds the agent's address to a meeting, their calendar mails the invitation, and the platform parses it into a matching event on the agent's primary calendar. The event arrives with the agent listed as a participant with status: "noreply"
and the organizer set to whoever sent it.
Three webhook triggers — event.created
, event.updated
, and event.deleted
— cover every change on the agent's calendar, whether the agent made it or a human responding to an invite did. The practical upshot: you can drive all your scheduling logic off event.created
and never inspect the invitation email. The event object already carries the organizer, participants, times, and description.
One mistake worth avoiding: having your agent reply to the invite email with "sounds good!" That updates nobody's calendar. The correct move is the dedicated endpoint:
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" }'
This sends a proper ICS REPLY
, so the organizer sees the agent as "accepted" next to every other attendee, and the other participants' calendars pick up the change automatically.
A few behaviors that surprised me on first read of the calendar docs:
event.created
(the parsed event) and message.created
(the email it rode in on). Pick one to drive your logic and ignore the other, or you'll double-process.no
or maybe
, then reply to the thread with an alternative. For real slot negotiation, Scheduler is the purpose-built tool and works with these accounts.timezone
at creation or stick to epoch start_time
/end_time
, like the example above does.POST /calendars/free-busy
returns the agent's busy blocks over a window, which is how an agent checks its own availability before proposing a slot.sales-calls
calendar and an internal
calendar on the same agent.Does the agent need a Google or Microsoft account to invite Google or Microsoft users? No. The invite is just an ICS REQUEST
riding on an email from the agent's own address. The recipient's provider parses it natively, exactly as it would an invite from any external organizer.
Can I drive everything from webhooks and never touch the mailbox? For calendar workflows, yes. The three event triggers (event.created
, event.updated
, event.deleted
) plus the event object's participants[].status
field carry everything: who organized, who's invited, who accepted, when it moved.
What about negotiating times back and forth? That's where the raw Events API stops and Scheduler starts. The Events API fits when the agent already knows the time and just needs to create the event or respond to an invite; Scheduler handles propose-pick-book round trips, and it works with Agent Accounts.
The protocol-level design means your scheduling agent inherits decades of calendar interop for free — no per-provider SDKs, no webhook adapters per platform. The fastest way to see it: run the quickstart, create an event with yourself as a participant, and accept it from your own Google or Outlook calendar. Watch the event.updated
webhook arrive when you click yes — then tell me that didn't feel a little uncanny.