# 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](/services).

## Before you start

The agent needs an open account. To mail guests or answer an organizer, the account needs an inbox: see [Email](/docs/account/email).

## Make an event

```text
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

```text
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](/docs/api/wake-ups). Every tool is in the [tool reference](/docs/mcp-tools).
