Skip to content
Skip to main content

Give your agent its own calendar

Give your AI agent a real calendar it owns and operates independently — not a seat on a human’s calendar. The agent hosts events under its own identity, RSVPs to invitations that arrive for it, and manages its schedule without cluttering anyone else’s calendar. This is the calendar surface of a Nylas Agent Account: a Nylas-hosted calendar you create and control entirely through the API.

Use this pattern when you want:

  • A scheduling agent that sends meeting invitations from [email protected] — participants accept or decline as if they’d booked with a human.
  • An event-hosting agent (office hours, product demos, support slots) that holds its own calendar and tracks RSVPs.
  • A multi-agent workflow where each agent books its own meetings and those meetings don’t pile up on a real employee’s calendar.

If you’d rather the agent manage events on your personal calendar, see Share your calendar with your agent instead.

Prerequisites

Section titled “Prerequisites”

Create the Agent Account

Section titled “Create the Agent Account”

An Agent Account covers email and calendar on the same grant. The fastest path is the Nylas CLI:

nylas agent account create [email protected]

Save the grant ID the CLI prints. A primary calendar is provisioned automatically — no extra call is needed before the agent can create events.

If you prefer the API, the same result from POST /v3/connect/custom with "provider": "nylas":

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "[email protected]"
    }
  }'

Create events on behalf of the agent

Section titled “Create events on behalf of the agent”

The agent creates events with POST /v3/grants/{grant_id}/events. When notify_participants is true, Nylas sends an ICS REQUEST to every invitee over standard iCalendar — recipients on Google Calendar, Microsoft 365, and Apple Calendar see it as a normal 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 with Alice",
    "when": { "start_time": 1771545600, "end_time": 1771549200 },
    "participants": [
      { "email": "[email protected]", "name": "Alice" }
    ]
  }'

RSVP to invitations the agent receives

Section titled “RSVP to invitations the agent receives”

When an external invitation lands in the agent’s inbox, the agent responds with POST /v3/grants/{grant_id}/events/{event_id}/send-rsvp. The RSVP goes out as an ICS REPLY and is visible to every participant.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events/<EVENT_ID>/send-rsvp" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{ "status": "yes" }'

List upcoming events

Section titled “List upcoming events”

The agent checks its schedule with GET /v3/grants/{grant_id}/events. Pass expand_recurring=true to materialize recurring instances:

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

Check when the agent is free

Section titled “Check when the agent is free”

Use GET /v3/grants/{grant_id}/calendars/free-busy to find gaps in the agent’s schedule before booking a new event:

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": 1771545600,
    "end_time": 1771718400,
    "emails": ["[email protected]"]
  }'

Receive webhooks when the schedule changes

Section titled “Receive webhooks when the schedule changes”

Subscribe to the calendar triggers so the agent reacts in real time — someone accepts an invite, a participant reschedules, an event is cancelled.

From the Nylas CLI:

nylas webhook create \
  --url https://youragent.example.com/webhooks/nylas \
  --triggers "event.created,event.updated,event.deleted"

Or through the API:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": ["event.created", "event.updated", "event.deleted"],
    "callback_url": "https://youragent.example.com/webhooks/nylas"
  }'

Combine with the agent’s email

Section titled “Combine with the agent’s email”

Because an Agent Account has both email and calendar on the same grant, a scheduling agent can:

  1. Receive a meeting request on the email side (message.created webhook).
  2. Parse the message with its LLM, pick candidate times.
  3. Reply on the email side with proposed slots via /messages/send.
  4. Create the event once the human confirms, inviting them from [email protected].
  5. Watch event.updated / event.deleted and follow up as needed.

The full surface is documented in Supported endpoints for Agent Accounts.

What’s next

Section titled “What’s next”