Dev.to
Scheduling Without a Human Calendar
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": 1744390800 },
"participants": [{ "email": "alice@example.com" }]
}'
With notify_participants=true, an invitation goes out from the agent's own address as a standard ICS request. Google Calendar, Microsoft 365, and Apple Calendar all render it as a normal invite, because under the hood it is one — plain iCalendar, the same protocol humans have used for decades.
RSVPs flow back without polling
The return path is the part borrowed-calendar setups handle worst, and here it's automatic. When Alice clicks Yes in Gmail, Google sends the response to the agent's mailbox, the platform parses it, updates the event's participants[].status, and fires an event.updated webhook. The agent learns who accepted without reading a single email.
The same machinery runs in reverse when the agent is the invitee. Someone adds the agent's address to their meeting; the invitation hits the mailbox, a matching event appears on the agent's calendar with its status as noreply, and event.created fires. The agent responds through the send-rsvp endpoint with one of 3 statuses — yes, no, or maybe — and the organizer sees it accepted like any other attendee. A plain reply email won't update anyone's calendar; the endpoint exists because RSVP is calendar protocol, not prose.
Changes propagate the same way: PUT /events/{id} updates the time or title on every participant's calendar, wherever they're looking at it, and DELETE /events/{id} removes it everywhere.
The small print that saves you a debugging session
A few mechanics from the calendar docs that aren't obvious until they bite:
Two webhooks fire for one invite. Because the agent is always a mailbox too, an inbound invitation triggers event.created and message.created for the invite email itself. Pick one to drive your logic and deliberately ignore the other, or you'll process every meeting twice.
notify_participants is a sharp tool. Every create, update, and delete with notify_participants=true sends real email. Pass false for bulk backfill or pre-staged events the agent will announce later — but not when cancelling, because deleting an event without notification leaves the meeting sitting on everyone's calendar.
The agent has no time zone. A human calendar carries a default; an Agent Account doesn't. Pass timezone explicitly on create, or stick to epoch start_time/end_time values.
One agent can run several calendars. The primary is provisioned automatically and can't be deleted while other calendars exist, and you can create more up to your plan's cap — a sales-calls calendar and an internal calendar on the same agent keeps concerns separate.
The honest limits
Two things the dedicated-identity model doesn't fix, and one operational note.
Negotiation isn't an endpoint. Counter-proposing a time isn't first-class today — the documented pattern is to RSVP no or maybe and reply with an alternative by email, letting the organizer recreate the event. If your flow is negotiation-heavy (propose slots to many people, collect picks, book the winner), the docs point you at Scheduler, which is built for round-trips and works with Agent Accounts. The Events API shines when the agent already knows the time.
Parsing is still the hard part. Owning the calendar removes the permissions problem, not the language problem. "Sometime late next week, ideally afternoon, I'm in Lisbon" still needs an LLM, and the tutorial is candid that wrong intent extraction creates real calendar chaos — it recommends human confirmation for first-time senders and high-value meetings.
Quotas apply. Every proposal and confirmation email counts against the account's send cap — 200 messages per account per day on the free plan — and for a busy agent it's worth setting an explicit policy before launch rather than discovering the ceiling in production.
The counterargument I'd actually respect: if your bot schedules on behalf of a specific person — managing a real executive's actual calendar — then borrowing that calendar is correct, because the availability that matters is theirs. Dedicated identity wins when the bot is the service itself: demo bookings, interview coordination, support callbacks. Pick the model that matches whose time is being scheduled.
If you've got an Agent Account already, here's a 15-minute experiment: create an event with yourself as participant and notify_participants=true, accept it from your phone, and watch the event.updated webhook arrive with your status change. Once you've seen the loop close end to end, the architecture mostly designs itself.
9 hours ago
