STACK
MENU
DOCS / THE ACCOUNT / CALENDAR

Calendar

How an agent makes events and invites guests, answers the invites it receives, reads its agenda, and how you see its calendar in your own calendar app. What the calendar is and what it costs is on Services.

Before you start

The agent needs an open account. To mail guests or answer an organizer, the account needs an inbox: see Email.

Make an event

prompt
Put a planning meeting on the assistant's calendar for Friday at 10 and invite anna@example.com.

The client calls stack_create_calendar_event. From code or the terminal:

typescript
const made = await stack.calendar.createEvent('acct_123', {
  title: 'Planning',
  start: '2026-11-20T10:00',
  time_zone: 'Europe/Stockholm',
  guests: ['anna@example.com'],
});
// made.event.id, made.notices.sent
bash
npx @getstackrun/cli calendar create acct_123 --title Planning \
  --start 2026-11-20T10:00 --tz Europe/Stockholm --guests anna@example.com
  • title and start are required.
  • A date alone (2026-11-20) is an all-day event. A time without an offset is local time in time_zone. A time with Z or an offset is an exact instant.
  • repeat takes an RFC 5545 rule, for example FREQ=WEEKLY;BYDAY=FR.
  • Guests are mailed an invite from the account's inbox. The event is stored even when a mail cannot go, and notices in the answer says why.
  • wake_minutes_before starts the agent ahead of each occurrence.
  • meeting: true gives the event a meeting room. See Meetings.

Change or cancel

stack_update_calendar_event and stack_cancel_calendar_event change and cancel. For a repeating event, occurrence with scope (series, occurrence or following) says which part. Guests are told by mail. A cancelled event cannot be changed again, and there is no delete.

Answer an invite

An invite that arrives in the inbox shows on the calendar. The agent answers it:

typescript
await stack.calendar.respond('acct_123', 'cev_abc', { response: 'accept' });
  • The tool is stack_respond_to_calendar_event. response is accept, tentative or decline.
  • The organizer is mailed the answer unless notify_organizer is false.
  • An accepted invite wakes the agent before each occurrence.
  • When a guest proposes another time, accept it with update and its counter_id, or turn it down with stack_decline_calendar_proposal.

Read the agenda

prompt
What is on the assistant's calendar next week?

The client calls stack_calendar_agenda with a from and a to, and gets every occurrence in that window. stack_list_calendar_events lists events, and can filter to invites not yet answered. Reads are free.

See it in your own calendar app

bash
npx @getstackrun/cli calendar feed acct_123 --rotate

This prints a feed URL that a calendar app can subscribe to. It is read-only. --revoke ends it.

The URL is shown once. Whoever holds it sees every event and the guests' addresses until you rotate or end it.

What counts as an action

Making, changing, cancelling, answering and turning down a proposal are one action each, however many guests are mailed. Mail to guests still counts toward the shared mail domain's daily recipients.

When it is refused

  • 409 CALENDAR_NO_INBOX - the event has guests and the account has no inbox.
  • 409 CALENDAR_NOT_ORGANIZER - an invite from someone else cannot be changed or cancelled. Answer it.
  • 409 CALENDAR_EVENT_CANCELLED - the event was cancelled.
  • 409 INVITE_NOT_RESPONDABLE - the invite was cancelled, has no start, or the account has no inbox to answer from.
  • 400 CALENDAR_INPUT_INVALID - a field is wrong. The answer names the field.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused the mail. Controls are asked as email.send for exactly the people mailed.

Reference

Every field is on Wake-ups, Calendar and Meetings. Every tool is in the tool reference.

Calendar | Docs