Give Your Scheduling Bot Its Own Calendar

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:

1. Human emails the agent. message.created fires; the webhook only carries summary fields, so the handler fetches the full body.
2. The LLM extracts duration, timezone, and urgency.
3. The agent queries /calendars/free-busy against its own primary calendar and replies with 3 candidate slots.
4. 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 busy blocks over a window; the agent generates candidate slots and filters out the overlaps:

const freeBusy = await nylas.calendars.getFreeBusy({
  identifier: AGENT_GRANT_ID,
  requestBody: {
    startTime: Math.floor(parsed.preferredWindow.start.getTime() / 1000),
    endTime: Math.floor(parsed.preferredWindow.end.getTime() / 1000),
    emails: ["scheduling@agents.yourcompany.com"],
  },
});

const openSlots = candidates.filter(
  (slot) => !overlapsAnyBusyBlock(slot, freeBusy.data),
);

The proposal reply then goes out through the standard send endpoint with replyToMessageId set, so it threads under the original request. The recipient sees a normal reply from the agent's address — no relay footer, no sent-via branding.

That last flag matters. With notify_participants=true, an ICS REQUEST goes out from the agent's address, and the recipient's calendar client renders it as a standard invitation:

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

When Alice clicks Yes in Gmail, Google sends the response back to the agent's mailbox, the event's participants[].status updates automatically, and event.updated fires — the agent knows who accepted without parsing a single email. Declines can trigger an LLM-drafted "here are some alternatives" reply; reschedule proposals can be answered with POST /events/{id}/send-rsvp and a status of yes, no, or maybe, which goes out as a standard ICS REPLY every participant sees.

Updates, cancellations, and the notify switch

notify_participants is a per-call decision, not a one-time setting, and it applies to the whole event lifecycle. A PUT /events/{id} with changed fields updates the meeting on every participant's calendar; DELETE /events/{id} removes it everywhere. Pass notify_participants=false when you want silence — pre-staging events the agent will announce later, or backfilling historical data without emailing anyone.

The trap is the inverse: deleting an event without notify_participants=true leaves the meeting sitting on participants' calendars. For a scheduling agent, cancel with notification unless you have a specific reason not to. One more timezone note from the calendars doc: an Agent Account has no default time zone the way a human's calendar does, so pass timezone on create or stick to epoch start_time/end_time.

The agent as invitee, not just organizer

It works in reverse too. When someone invites the agent to their meeting, the invitation flows through the mailbox, Nylas parses it, and a matching event appears on the agent's primary calendar with the agent's status set to noreply. You drive the response logic entirely off the event.created webhook — the event object already carries the organizer, participants, and times. One gotcha from the calendars doc: the invite email also fires message.created, so decide which webhook drives your logic and ignore the other, or you'll process every invitation twice.

Field notes worth stealing

A few things the tutorial calls out that are easy to learn the hard way:

• Threading is testable — test it. Replies must preserve Message-ID, In-Reply-To, and References so the conversation threads in Gmail and Outlook. Nylas preserves these on outbound; send yourself a request and verify the reply lands in the original thread before launch.
• Watch the send cap. Free-plan Agent Accounts send up to 200 messages per account per day, and a busy scheduling agent — proposals, confirmations, reminders — can get there. Paid plans have no daily cap by default; a policy can also set a stricter quota. Sort this before launch, not after the first missed confirmation.
• Don't tunnel through ngrok. Nylas blocks webhook URLs on ngrok because of throughput limiting; use VS Code port forwarding or Hookdeck for local development.
• Humans can supervise over IMAP. Set app_password on the grant and your ops team can open the agent's mailbox in Outlook or Apple Mail to audit replies and intervene — every IMAP action syncs back to the API.
• Separate calendars for separate concerns. Beyond the primary, you can create additional calendars up to your plan's cap — say, sales-calls and internal on the same agent.
• The agent can't see mail it never receives. A request routed to junk won't fire a message.created on the inbox. If you run spam rules, audit them with the rule evaluations endpoint so important senders aren't silently filtered.
• Wrong parses create real calendar chaos. Latency is forgiving here (minutes, not milliseconds), but intent extraction errors are not. Require human confirmation for first-time senders or high-value meetings.
• One agent per role. Scheduling, support, and outreach want different quotas and spam sensitivities. Model each as its own account with its own policy.

Counter-proposing a time isn't a first-class endpoint today — the common pattern is RSVP no or maybe plus a reply proposing alternatives. For heavily negotiated multi-participant flows, Scheduler is purpose-built and works with Agent Accounts.

If you want to try this, the fastest start is a trial *.nylas.email subdomain: provision the account, create one event with notify_participants=true, and accept it from your personal calendar. Watching event.updated arrive the moment you click Yes is the point where the architecture clicks. What's your tolerance for letting the LLM book without human confirmation — and where would you draw that line?