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

• A Nylas API key. If you don’t have one, follow the Getting started with the CLI or Dashboard guide.
• A domain registered with Nylas — either a Nylas-provided *.nylas.email trial subdomain or your own domain with MX + TXT records in place. See Setup domains.

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

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

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

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

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

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

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

• Agent Accounts overview — the full product doc, including capabilities, limits, and architecture
• Agent Accounts quickstart — step-by-step setup and first end-to-end send/receive
• Give your agent its own email — use the same grant for the agent’s inbox
• Supported endpoints for Agent Accounts — every calendar and event endpoint Agent Accounts expose
• Webhook notifications — payload schemas for the event and message triggers