How Agent Calendars Speak ICS to Google and Microsoft

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.

The protocol nobody had to invent

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.

When the agent hosts

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&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" }
    ]
  }'

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&notify_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.

When the agent is invited

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.

RSVPs are calendar messages, not emails

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.

Edge cases worth knowing

A few behaviors that surprised me on first read of the calendar docs:

Every invite fires twice, sort of. An inbound invitation triggers both 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.
Counter-proposing isn't first-class. There's no "propose new time" endpoint today. The pattern is RSVP 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.
The account has no default time zone. Times live on the event — pass timezone at creation or stick to epoch start_time/end_time, like the example above does.
Free/busy works. 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.
You're not limited to one calendar. The primary calendar is provisioned automatically (and can't be deleted while others exist), but you can create additional ones up to your plan's cap — say, a sales-calls calendar and an internal calendar on the same agent.

Quick FAQ

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.

Try it

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.

推荐订阅源

DEV Community