---
title: "Calendar"
description: "Events and invitations."
url: "https://openemail.uk/docs/mcp/tools/calendar"
area: "MCP server"
category: "Tools"
---

# Calendar

Events and invitations.

## Calendar tools

| Tool | What it does |
| --- | --- |
| listCalendarEvents | Every occurrence between two moments, a repeating event once for each time it happens, with its place, status and your answer. |
| getCalendarEvent | One event in full, by `id` or by the `threadId` of the conversation that carries its invitation: the attendees and their answers, how it repeats and its reminders. |
| createCalendarEvent | Put an event on the calendar and invite the attendees from an address you may send as. In the app’s chat it asks first unless you asked for it. |
| updateCalendarEvent | Change an event you organise, and send the update to everyone invited. In the app’s chat it asks first unless you asked for it. |
| cancelCalendarEvent | Call off a meeting you organise and tell everyone invited. In the app’s chat it always asks first. |
| deleteCalendarEvent | Take an event off the calendar without telling anybody. In the app’s chat it always asks first. |
| respondToCalendarEvent | Accept, decline or tentatively accept an invitation, and tell the organiser. In the app’s chat it asks first unless you asked for it. |

> Reading needs `calendar:read` and every change needs `calendar:write`. Anything that emails somebody also needs `emails:send`: inviting, updating or cancelling a meeting with attendees, and every answer to an invitation.

> A client limited to some addresses sees and changes only the events one of them organises or attends, and sends only from them.

## Reference

### `listCalendarEvents`

The calendar between two moments, as the Calendar page of the app shows it: every occurrence in the window, a repeating event once for each time it happens, sorted by start, with its event id, place, status and your answer. from and to are ISO 8601 with a zone, at most a year apart, and timezone (an IANA zone, UTC unless you say) decides what an all-day event means. When more follow, the last line gives the offset to pass back.

- Scopes: `calendar:read`.
- The app's assistant runs it without asking.
- Toolkit: `calendar`.

**Inputs**

- `from` (`string`, required, format `date-time`)
- `to` (`string`, required, format `date-time`)
- `timezone` (`string`, 1 to 64 characters)
- `limit` (`integer`, at least 1, at most 200)
- `offset` (`integer`, at least 0)

Also available in: API [`GET /calendar/events`](https://openemail.uk/docs/api/reference/calendar#get-calendar-events); SDK [`calendar.listEvents()`](https://openemail.uk/docs/sdk/reference/calendar#listEvents), [`calendar.listAllEvents()`](https://openemail.uk/docs/sdk/reference/calendar#listAllEvents), [`calendar.iterateEvents()`](https://openemail.uk/docs/sdk/reference/calendar#iterateEvents).

### `getCalendarEvent`

One calendar event in full: when it is, where, who organised it, every attendee and their answer, your own answer, how it repeats and its reminders. Pass id for an event from listCalendarEvents, or threadId for the invitation a conversation carries.

- Scopes: `calendar:read`.
- The app's assistant runs it without asking.
- Toolkit: `calendar`.

**Inputs**

- `id` (`string`, 1 to 64 characters)
- `threadId` (`string`, 1 to 256 characters)

Also available in: API [`GET /calendar/events/{id}`](https://openemail.uk/docs/api/reference/calendar#get-calendar-events-id), [`GET /threads/{id}/event`](https://openemail.uk/docs/api/reference/calendar#get-threads-id-event); SDK [`calendar.getEvent()`](https://openemail.uk/docs/sdk/reference/calendar#getEvent), [`threads.getEvent()`](https://openemail.uk/docs/sdk/reference/threads#getEvent).

### `createCalendarEvent`

Put an event on the calendar, as New event on the Calendar page does. start and end are ISO 8601 with a zone. With attendees, an invitation goes to each of them from the address in from, which has to be one you may send as, unless sendInvites is false. reminders takes minutes before the start, and recurrence an RRULE such as FREQ=WEEKLY;BYDAY=MO.

- Scopes: `calendar:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `calendar`.

**Inputs**

- `summary` (`string`, required, 1 to 255 characters)
- `start` (`string`, required, format `date-time`)
- `end` (`string`, required, format `date-time`)
- `description` (`string`, up to 8000 characters)
- `location` (`string`, up to 255 characters)
- `url` (`string`, up to 2000 characters, format `uri`)
- `allDay` (`boolean`)
- `timezone` (`string`, 1 to 64 characters)
- `recurrence` (`string`, up to 512 characters)
- `attendees` (`object[]`, up to 200 items)
  - `email` (`string`, required, up to 320 characters, format `email`)
  - `name` (`string`, up to 128 characters)
  - `optional` (`boolean`)
- `reminders` (`object[]`, up to 5 items)
  - `minutesBefore` (`integer`, required, at least 0, at most 40320)
- `sendInvites` (`boolean`)
- `from` (`string`, up to 320 characters)

Also available in: API [`POST /calendar/events`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events); SDK [`calendar.createEvent()`](https://openemail.uk/docs/sdk/reference/calendar#createEvent).

### `updateCalendarEvent`

Change an event you organise: its title, time, place, attendees, reminders or repeating. A field left out keeps its value, and attendees replaces the whole list. Everyone invited gets the updated invitation unless sendInvites is false.

- Scopes: `calendar:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `calendar`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `summary` (`string`, 1 to 255 characters)
- `start` (`string`, format `date-time`)
- `end` (`string`, format `date-time`)
- `description` (`string`, up to 8000 characters)
- `location` (`string`, up to 255 characters)
- `url` (`string`, up to 2000 characters, format `uri`)
- `allDay` (`boolean`)
- `timezone` (`string`, 1 to 64 characters)
- `recurrence` (`string`, up to 512 characters)
- `attendees` (`object[]`, up to 200 items)
  - `email` (`string`, required, up to 320 characters, format `email`)
  - `name` (`string`, up to 128 characters)
  - `optional` (`boolean`)
- `reminders` (`object[]`, up to 5 items)
  - `minutesBefore` (`integer`, required, at least 0, at most 40320)
- `sendInvites` (`boolean`)
- `from` (`string`, up to 320 characters)

Also available in: API [`PATCH /calendar/events/{id}`](https://openemail.uk/docs/api/reference/calendar#patch-calendar-events-id); SDK [`calendar.updateEvent()`](https://openemail.uk/docs/sdk/reference/calendar#updateEvent).

### `cancelCalendarEvent`

Call off a meeting you organise, as Cancel meeting does in the app: it stays on the calendar marked cancelled, and everyone invited is told it is off, from the address in from. A chat always asks first.

- Scopes: `calendar:write`.
- The app's assistant always asks first.
- Toolkit: `calendar`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `from` (`string`, up to 320 characters)

Also available in: API [`POST /calendar/events/{id}/cancel`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events-id-cancel); SDK [`calendar.cancelEvent()`](https://openemail.uk/docs/sdk/reference/calendar#cancelEvent).

### `deleteCalendarEvent`

Remove an event from the calendar for good, as Remove does in the app. Nobody else is told, so call off a meeting with others in it with cancelCalendarEvent instead. A chat always asks first.

- Scopes: `calendar:write`.
- The app's assistant always asks first.
- Toolkit: `calendar`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)

Also available in: API [`DELETE /calendar/events/{id}`](https://openemail.uk/docs/api/reference/calendar#delete-calendar-events-id); SDK [`calendar.deleteEvent()`](https://openemail.uk/docs/sdk/reference/calendar#deleteEvent).

### `respondToCalendarEvent`

Answer an invitation: ACCEPTED, DECLINED or TENTATIVE. The answer goes to the organiser by email from the invited address you may send as, or from respondingAs when the invitation went to more than one of yours.

- Scopes: `calendar:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `calendar`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `response` (`string`, required, one of `"ACCEPTED"`, `"DECLINED"`, `"TENTATIVE"`)
- `respondingAs` (`string`, up to 320 characters)

Also available in: API [`POST /calendar/events/{id}/respond`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events-id-respond); SDK [`calendar.respondToEvent()`](https://openemail.uk/docs/sdk/reference/calendar#respondToEvent).