---
title: "Calendar"
description: "Events, invitations, calendar links and subscriptions."
url: "https://nextmail.sh/docs/mcp/tools/calendar"
area: "MCP server"
category: "Tools"
---

# Calendar

Events, invitations, calendar links and subscriptions.

## Calendar tools

| Tool | What it does |
| --- | --- |
| listCalendarEvents | Your occurrences between two moments, a repeating event once for each time it happens, with its place, status and your answer. The owner adds the team with `includeTeam`. |
| 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, or propose a new time with your answer, and tell the organiser. In the app’s chat it asks first unless you asked for it. |
| declineCalendarProposal | Keep the original time of a meeting you organise after a guest proposed another one, and tell the guest. In the app’s chat it asks first unless you asked for it. |
| listCalendarFeeds | The secret links that publish your calendar to Google Calendar, Outlook or Apple Calendar, with their addresses. |
| createCalendarFeed | Make a secret link that publishes your calendar, with every detail or busy times only. In the app’s chat it always asks first. |
| resetCalendarFeed | Give a calendar link a new address, so the old one stops working. In the app’s chat it always asks first. |
| deleteCalendarFeed | Turn a calendar link off for good. In the app’s chat it always asks first. |
| listCalendarSubscriptions | The other calendars you subscribe to by link, and whether each is read without errors. |
| subscribeToCalendar | Add another calendar by its iCalendar link, such as a Google or Outlook calendar address, so its events show read-only. In the app’s chat it always asks first. |
| updateCalendarSubscription | Rename a calendar subscription or change its colour. In the app’s chat it asks first unless you asked for it. |
| refreshCalendarSubscription | Read a subscribed calendar again now, and restart one that stopped after failures. |
| unsubscribeFromCalendar | Remove a calendar subscription and the events it brought. In the app’s chat it always asks first. |
| listCalendarImports | The calendar files and calendars brought in, newest first, with how many events each added, found already here and left out. |
| getCalendarImport | One calendar import with its report: the calendars it read and what it left out, and why. |
| undoCalendarImport | Remove every event one calendar import added. Nobody is told. In the app’s chat it always asks first. |
| hideCalendarEvent | Hide an event from your own calendar and leave it for everyone else, or show it again. In the app’s chat it asks first unless you asked for it. |
| findMeetingTime | When people of the workspace are busy, and the first times everyone is free for a meeting of the length you give. |

> 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, every answer to an invitation, and declining a proposed time.

> A client limited to some addresses sees and changes only the events one of them organises or attends, and sends only from them. It cannot manage calendar links or subscriptions, which cover the whole calendar of the person it acts for.

> An event that came in through a calendar import emails nobody by default. `updateCalendarEvent` tells its guests only with `sendInvites` true, and `cancelCalendarEvent` and `respondToCalendarEvent` only with `notifyGuests` true. No tool uploads a calendar file: upload an .ics file in the Calendars dialog of the app or with `POST /calendar/imports`, then read or undo the import here.

> For a repeating event, `updateCalendarEvent`, `cancelCalendarEvent` and `deleteCalendarEvent` take `scope` with `occurrenceStart`: `occurrence` reaches one date, `following` that date and every one after it, and `series` all of them. `findMeetingTime` refuses a client limited to some addresses, since it reads whole calendars.

> `listCalendarEvents` takes `q`, words that every event it returns holds in its title, its place or its organiser, so a window of up to a year finds an event by name.

## 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. It lists your own events: the ones you made and the ones an address of yours organises or attends. For the workspace owner, includeTeam: true adds the rest of the workspace, apart from events somebody marked private. q keeps the events whose title, place or organiser holds every word, so pass a window of up to a year with it to find an event by name.

- 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)
- `includeTeam` (`boolean`)
- `q` (`string`, up to 200 characters): Words to look for in the title, the place and the organiser. Only events that hold every word come back, so search a long window, at most a year, to find an event by name.
- `limit` (`integer`, at least 1, at most 200)
- `offset` (`integer`, at least 0)

Also available in: API [`GET /calendar/events`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-events); TypeScript [`nextmail.calendar.listEvents()`](https://nextmail.sh/docs/sdk/reference/calendar#listEvents), [`nextmail.calendar.listAllEvents()`](https://nextmail.sh/docs/sdk/reference/calendar#listAllEvents), [`nextmail.calendar.iterateEvents()`](https://nextmail.sh/docs/sdk/reference/calendar#iterateEvents); Python [`calendar.list_events()`](https://nextmail.sh/docs/python/reference/calendar#listEvents), [`calendar.list_all_events()`](https://nextmail.sh/docs/python/reference/calendar#listAllEvents), [`calendar.iterate_events()`](https://nextmail.sh/docs/python/reference/calendar#iterateEvents); Ruby [`calendar.list_events`](https://nextmail.sh/docs/ruby/reference/calendar#listEvents), [`calendar.list_all_events`](https://nextmail.sh/docs/ruby/reference/calendar#listAllEvents), [`calendar.iterate_events`](https://nextmail.sh/docs/ruby/reference/calendar#iterateEvents); PHP [`calendar->listEvents`](https://nextmail.sh/docs/php/reference/calendar#listEvents), [`calendar->listAllEvents`](https://nextmail.sh/docs/php/reference/calendar#listAllEvents), [`calendar->iterateEvents`](https://nextmail.sh/docs/php/reference/calendar#iterateEvents); Go [`Calendar.ListEvents`](https://nextmail.sh/docs/go/reference/calendar#listEvents), [`Calendar.ListAllEvents`](https://nextmail.sh/docs/go/reference/calendar#listAllEvents), [`Calendar.IterateEvents`](https://nextmail.sh/docs/go/reference/calendar#iterateEvents); Java [`calendar().listEvents`](https://nextmail.sh/docs/java/reference/calendar#listEvents), [`calendar().listAllEvents`](https://nextmail.sh/docs/java/reference/calendar#listAllEvents), [`calendar().iterateEvents`](https://nextmail.sh/docs/java/reference/calendar#iterateEvents); C# [`Calendar.ListEventsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listEvents), [`Calendar.ListAllEventsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listAllEvents), [`Calendar.IterateEventsAsync`](https://nextmail.sh/docs/csharp/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://nextmail.sh/docs/api/reference/calendar#get-calendar-events-id), [`GET /threads/{id}/event`](https://nextmail.sh/docs/api/reference/calendar#get-threads-id-event); TypeScript [`nextmail.calendar.getEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#getEvent), [`nextmail.threads.getEvent()`](https://nextmail.sh/docs/sdk/reference/threads#getEvent); Python [`calendar.get_event()`](https://nextmail.sh/docs/python/reference/calendar#getEvent), [`threads.get_event()`](https://nextmail.sh/docs/python/reference/threads#getEvent); Ruby [`calendar.get_event`](https://nextmail.sh/docs/ruby/reference/calendar#getEvent), [`threads.get_event`](https://nextmail.sh/docs/ruby/reference/threads#getEvent); PHP [`calendar->getEvent`](https://nextmail.sh/docs/php/reference/calendar#getEvent), [`threads->getEvent`](https://nextmail.sh/docs/php/reference/threads#getEvent); Go [`Calendar.GetEvent`](https://nextmail.sh/docs/go/reference/calendar#getEvent), [`Threads.GetEvent`](https://nextmail.sh/docs/go/reference/threads#getEvent); Java [`calendar().getEvent`](https://nextmail.sh/docs/java/reference/calendar#getEvent), [`threads().getEvent`](https://nextmail.sh/docs/java/reference/threads#getEvent); C# [`Calendar.GetEventAsync`](https://nextmail.sh/docs/csharp/reference/calendar#getEvent), [`Threads.GetEventAsync`](https://nextmail.sh/docs/csharp/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`)
- `meetingUrl` (`string`, up to 2000 characters): A link to the video call, such as a Zoom, Meet or Teams address. It goes into the invitation, so guests see a Join button in their calendar too. Send an empty string to take it off.
- `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)
  - `action` (`string`, one of `"DISPLAY"`, `"EMAIL"`, `"AUDIO"`): DISPLAY, the default, shows a reminder; EMAIL sends one; AUDIO plays a sound.
- `transparency` (`string`, one of `"OPAQUE"`, `"TRANSPARENT"`): OPAQUE, the default, shows the time as busy; TRANSPARENT leaves it free.
- `visibility` (`string`, one of `"PUBLIC"`, `"PRIVATE"`, `"CONFIDENTIAL"`): PUBLIC, PRIVATE or CONFIDENTIAL: how much a calendar shared with others shows of it.
- `sendInvites` (`boolean`)
- `from` (`string`, up to 320 characters)

Also available in: API [`POST /calendar/events`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events); TypeScript [`nextmail.calendar.createEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#createEvent); Python [`calendar.create_event()`](https://nextmail.sh/docs/python/reference/calendar#createEvent); Ruby [`calendar.create_event`](https://nextmail.sh/docs/ruby/reference/calendar#createEvent); PHP [`calendar->createEvent`](https://nextmail.sh/docs/php/reference/calendar#createEvent); Go [`Calendar.CreateEvent`](https://nextmail.sh/docs/go/reference/calendar#createEvent); Java [`calendar().createEvent`](https://nextmail.sh/docs/java/reference/calendar#createEvent); C# [`Calendar.CreateEventAsync`](https://nextmail.sh/docs/csharp/reference/calendar#createEvent).

### `updateCalendarEvent`

Change an event you organise: its title, time, place, video call link, 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. An event that came in through a calendar import tells nobody unless sendInvites is true. For a repeating event, scope occurrence with occurrenceStart changes one date, following changes that date and the ones after it, and series changes them all.

- 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`)
- `meetingUrl` (`string`, up to 2000 characters): A link to the video call, such as a Zoom, Meet or Teams address. It goes into the invitation, so guests see a Join button in their calendar too. Send an empty string to take it off.
- `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)
  - `action` (`string`, one of `"DISPLAY"`, `"EMAIL"`, `"AUDIO"`): DISPLAY, the default, shows a reminder; EMAIL sends one; AUDIO plays a sound.
- `transparency` (`string`, one of `"OPAQUE"`, `"TRANSPARENT"`): OPAQUE, the default, shows the time as busy; TRANSPARENT leaves it free.
- `visibility` (`string`, one of `"PUBLIC"`, `"PRIVATE"`, `"CONFIDENTIAL"`): PUBLIC, PRIVATE or CONFIDENTIAL: how much a calendar shared with others shows of it.
- `sendInvites` (`boolean`)
- `from` (`string`, up to 320 characters)
- `scope` (`string`, one of `"occurrence"`, `"following"`, `"series"`): Which dates the change reaches when the event repeats: `occurrence` for the one date in `occurrenceStart`, `following` for that date and every one after it, or `series` for all of them. Left out, the change reaches the event or date the id names.
- `occurrenceStart` (`string`, format `date-time`): The start of the date you mean, as it appears in the list of events. Needed with `occurrence` and `following`.

Also available in: API [`PATCH /calendar/events/{id}`](https://nextmail.sh/docs/api/reference/calendar#patch-calendar-events-id); TypeScript [`nextmail.calendar.updateEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#updateEvent); Python [`calendar.update_event()`](https://nextmail.sh/docs/python/reference/calendar#updateEvent); Ruby [`calendar.update_event`](https://nextmail.sh/docs/ruby/reference/calendar#updateEvent); PHP [`calendar->updateEvent`](https://nextmail.sh/docs/php/reference/calendar#updateEvent); Go [`Calendar.UpdateEvent`](https://nextmail.sh/docs/go/reference/calendar#updateEvent); Java [`calendar().updateEvent`](https://nextmail.sh/docs/java/reference/calendar#updateEvent); C# [`Calendar.UpdateEventAsync`](https://nextmail.sh/docs/csharp/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. An event that came in through a calendar import tells nobody unless notifyGuests is true, and notifyGuests false keeps any cancellation quiet. For a repeating meeting, scope occurrence with occurrenceStart calls off one date, and following that date and the ones after it. 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)
- `notifyGuests` (`boolean`)
- `scope` (`string`, one of `"occurrence"`, `"following"`, `"series"`): Which dates the change reaches when the event repeats: `occurrence` for the one date in `occurrenceStart`, `following` for that date and every one after it, or `series` for all of them. Left out, the change reaches the event or date the id names.
- `occurrenceStart` (`string`, format `date-time`): The start of the date you mean, as it appears in the list of events. Needed with `occurrence` and `following`.

Also available in: API [`POST /calendar/events/{id}/cancel`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events-id-cancel); TypeScript [`nextmail.calendar.cancelEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#cancelEvent); Python [`calendar.cancel_event()`](https://nextmail.sh/docs/python/reference/calendar#cancelEvent); Ruby [`calendar.cancel_event`](https://nextmail.sh/docs/ruby/reference/calendar#cancelEvent); PHP [`calendar->cancelEvent`](https://nextmail.sh/docs/php/reference/calendar#cancelEvent); Go [`Calendar.CancelEvent`](https://nextmail.sh/docs/go/reference/calendar#cancelEvent); Java [`calendar().cancelEvent`](https://nextmail.sh/docs/java/reference/calendar#cancelEvent); C# [`Calendar.CancelEventAsync`](https://nextmail.sh/docs/csharp/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. For a repeating event, scope occurrence with occurrenceStart removes one date, and following that date and the ones after it. 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)
- `scope` (`string`, one of `"occurrence"`, `"following"`, `"series"`): Which dates the change reaches when the event repeats: `occurrence` for the one date in `occurrenceStart`, `following` for that date and every one after it, or `series` for all of them. Left out, the change reaches the event or date the id names.
- `occurrenceStart` (`string`, format `date-time`): The start of the date you mean, as it appears in the list of events. Needed with `occurrence` and `following`.

Also available in: API [`DELETE /calendar/events/{id}`](https://nextmail.sh/docs/api/reference/calendar#delete-calendar-events-id); TypeScript [`nextmail.calendar.deleteEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#deleteEvent); Python [`calendar.delete_event()`](https://nextmail.sh/docs/python/reference/calendar#deleteEvent); Ruby [`calendar.delete_event`](https://nextmail.sh/docs/ruby/reference/calendar#deleteEvent); PHP [`calendar->deleteEvent`](https://nextmail.sh/docs/php/reference/calendar#deleteEvent); Go [`Calendar.DeleteEvent`](https://nextmail.sh/docs/go/reference/calendar#deleteEvent); Java [`calendar().deleteEvent`](https://nextmail.sh/docs/java/reference/calendar#deleteEvent); C# [`Calendar.DeleteEventAsync`](https://nextmail.sh/docs/csharp/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. On an event that came in through a calendar import the answer is only recorded, and the organiser is told when notifyGuests is true.

- 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)
- `notifyGuests` (`boolean`)
- `proposedStart` (`string`, format `date-time`)
- `proposedEnd` (`string`, format `date-time`)

Also available in: API [`POST /calendar/events/{id}/respond`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events-id-respond); TypeScript [`nextmail.calendar.respondToEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#respondToEvent); Python [`calendar.respond_to_event()`](https://nextmail.sh/docs/python/reference/calendar#respondToEvent); Ruby [`calendar.respond_to_event`](https://nextmail.sh/docs/ruby/reference/calendar#respondToEvent); PHP [`calendar->respondToEvent`](https://nextmail.sh/docs/php/reference/calendar#respondToEvent); Go [`Calendar.RespondToEvent`](https://nextmail.sh/docs/go/reference/calendar#respondToEvent); Java [`calendar().respondToEvent`](https://nextmail.sh/docs/java/reference/calendar#respondToEvent); C# [`Calendar.RespondToEventAsync`](https://nextmail.sh/docs/csharp/reference/calendar#respondToEvent).

### `declineCalendarProposal`

Keep the original time of a meeting you organise after a guest proposed another one. The guest is told by email. To take the proposed time instead, change the event with updateCalendarEvent. A chat asks first unless you asked for it.

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

**Inputs**

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

Also available in: API [`POST /calendar/events/{id}/decline-proposal`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events-id-decline-proposal); TypeScript [`nextmail.calendar.declineProposal()`](https://nextmail.sh/docs/sdk/reference/calendar#declineProposal); Python [`calendar.decline_proposal()`](https://nextmail.sh/docs/python/reference/calendar#declineProposal); Ruby [`calendar.decline_proposal`](https://nextmail.sh/docs/ruby/reference/calendar#declineProposal); PHP [`calendar->declineProposal`](https://nextmail.sh/docs/php/reference/calendar#declineProposal); Go [`Calendar.DeclineProposal`](https://nextmail.sh/docs/go/reference/calendar#declineProposal); Java [`calendar().declineProposal`](https://nextmail.sh/docs/java/reference/calendar#declineProposal); C# [`Calendar.DeclineProposalAsync`](https://nextmail.sh/docs/csharp/reference/calendar#declineProposal).

### `listCalendarFeeds`

List the secret links that publish your calendar to other calendar apps such as Google Calendar, Outlook or Apple Calendar: full details or busy times only.

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

**Inputs**

Takes no input.

Also available in: API [`GET /calendar/feeds`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-feeds); TypeScript [`nextmail.calendar.listFeeds()`](https://nextmail.sh/docs/sdk/reference/calendar#listFeeds); Python [`calendar.list_feeds()`](https://nextmail.sh/docs/python/reference/calendar#listFeeds); Ruby [`calendar.list_feeds`](https://nextmail.sh/docs/ruby/reference/calendar#listFeeds); PHP [`calendar->listFeeds`](https://nextmail.sh/docs/php/reference/calendar#listFeeds); Go [`Calendar.ListFeeds`](https://nextmail.sh/docs/go/reference/calendar#listFeeds); Java [`calendar().listFeeds`](https://nextmail.sh/docs/java/reference/calendar#listFeeds); C# [`Calendar.ListFeedsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listFeeds).

### `createCalendarFeed`

Make a secret link that publishes your calendar, to paste into Google Calendar (From URL), Outlook (Subscribe from web) or Apple Calendar. mode full shows every detail, busy only the times you are busy. Anyone with the link can read it. A chat always asks first.

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

**Inputs**

- `name` (`string`, required, 1 to 100 characters)
- `mode` (`string`, required, one of `"full"`, `"busy"`)

Also available in: API [`POST /calendar/feeds`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-feeds); TypeScript [`nextmail.calendar.createFeed()`](https://nextmail.sh/docs/sdk/reference/calendar#createFeed); Python [`calendar.create_feed()`](https://nextmail.sh/docs/python/reference/calendar#createFeed); Ruby [`calendar.create_feed`](https://nextmail.sh/docs/ruby/reference/calendar#createFeed); PHP [`calendar->createFeed`](https://nextmail.sh/docs/php/reference/calendar#createFeed); Go [`Calendar.CreateFeed`](https://nextmail.sh/docs/go/reference/calendar#createFeed); Java [`calendar().createFeed`](https://nextmail.sh/docs/java/reference/calendar#createFeed); C# [`Calendar.CreateFeedAsync`](https://nextmail.sh/docs/csharp/reference/calendar#createFeed).

### `resetCalendarFeed`

Replace the secret in a calendar link, so the old address stops working everywhere it was shared. 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 [`POST /calendar/feeds/{id}/reset`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-feeds-id-reset); TypeScript [`nextmail.calendar.resetFeed()`](https://nextmail.sh/docs/sdk/reference/calendar#resetFeed); Python [`calendar.reset_feed()`](https://nextmail.sh/docs/python/reference/calendar#resetFeed); Ruby [`calendar.reset_feed`](https://nextmail.sh/docs/ruby/reference/calendar#resetFeed); PHP [`calendar->resetFeed`](https://nextmail.sh/docs/php/reference/calendar#resetFeed); Go [`Calendar.ResetFeed`](https://nextmail.sh/docs/go/reference/calendar#resetFeed); Java [`calendar().resetFeed`](https://nextmail.sh/docs/java/reference/calendar#resetFeed); C# [`Calendar.ResetFeedAsync`](https://nextmail.sh/docs/csharp/reference/calendar#resetFeed).

### `deleteCalendarFeed`

Turn a calendar link off for good. Calendar apps subscribed to it stop getting updates. 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/feeds/{id}`](https://nextmail.sh/docs/api/reference/calendar#delete-calendar-feeds-id); TypeScript [`nextmail.calendar.deleteFeed()`](https://nextmail.sh/docs/sdk/reference/calendar#deleteFeed); Python [`calendar.delete_feed()`](https://nextmail.sh/docs/python/reference/calendar#deleteFeed); Ruby [`calendar.delete_feed`](https://nextmail.sh/docs/ruby/reference/calendar#deleteFeed); PHP [`calendar->deleteFeed`](https://nextmail.sh/docs/php/reference/calendar#deleteFeed); Go [`Calendar.DeleteFeed`](https://nextmail.sh/docs/go/reference/calendar#deleteFeed); Java [`calendar().deleteFeed`](https://nextmail.sh/docs/java/reference/calendar#deleteFeed); C# [`Calendar.DeleteFeedAsync`](https://nextmail.sh/docs/csharp/reference/calendar#deleteFeed).

### `listCalendarSubscriptions`

List the other calendars you subscribe to by link, such as a Google or Outlook calendar, a team rota or public holidays, with whether each is read without errors.

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

**Inputs**

Takes no input.

Also available in: API [`GET /calendar/subscriptions`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-subscriptions); TypeScript [`nextmail.calendar.listSubscriptions()`](https://nextmail.sh/docs/sdk/reference/calendar#listSubscriptions); Python [`calendar.list_subscriptions()`](https://nextmail.sh/docs/python/reference/calendar#listSubscriptions); Ruby [`calendar.list_subscriptions`](https://nextmail.sh/docs/ruby/reference/calendar#listSubscriptions); PHP [`calendar->listSubscriptions`](https://nextmail.sh/docs/php/reference/calendar#listSubscriptions); Go [`Calendar.ListSubscriptions`](https://nextmail.sh/docs/go/reference/calendar#listSubscriptions); Java [`calendar().listSubscriptions`](https://nextmail.sh/docs/java/reference/calendar#listSubscriptions); C# [`Calendar.ListSubscriptionsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listSubscriptions).

### `subscribeToCalendar`

Add another calendar by its iCalendar link (https, http or webcal), such as the secret address of a Google calendar or a published Outlook calendar. Its events show on your calendar, read-only, and are read again about every half hour. A chat always asks first.

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

**Inputs**

- `url` (`string`, required, 1 to 2048 characters)
- `name` (`string`, 1 to 100 characters)
- `color` (`string`, one of `"blue"`, `"sky"`, `"teal"`, `"green"`, `"lime"`, `"yellow"`, `"orange"`, `"red"`, `"pink"`, `"purple"`, `"gray"`)

Also available in: API [`POST /calendar/subscriptions`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-subscriptions); TypeScript [`nextmail.calendar.createSubscription()`](https://nextmail.sh/docs/sdk/reference/calendar#createSubscription); Python [`calendar.create_subscription()`](https://nextmail.sh/docs/python/reference/calendar#createSubscription); Ruby [`calendar.create_subscription`](https://nextmail.sh/docs/ruby/reference/calendar#createSubscription); PHP [`calendar->createSubscription`](https://nextmail.sh/docs/php/reference/calendar#createSubscription); Go [`Calendar.CreateSubscription`](https://nextmail.sh/docs/go/reference/calendar#createSubscription); Java [`calendar().createSubscription`](https://nextmail.sh/docs/java/reference/calendar#createSubscription); C# [`Calendar.CreateSubscriptionAsync`](https://nextmail.sh/docs/csharp/reference/calendar#createSubscription).

### `updateCalendarSubscription`

Rename a calendar subscription or give it another colour.

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

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `name` (`string`, 1 to 100 characters)
- `color` (`string`, one of `"blue"`, `"sky"`, `"teal"`, `"green"`, `"lime"`, `"yellow"`, `"orange"`, `"red"`, `"pink"`, `"purple"`, `"gray"`)

Also available in: API [`PATCH /calendar/subscriptions/{id}`](https://nextmail.sh/docs/api/reference/calendar#patch-calendar-subscriptions-id); TypeScript [`nextmail.calendar.updateSubscription()`](https://nextmail.sh/docs/sdk/reference/calendar#updateSubscription); Python [`calendar.update_subscription()`](https://nextmail.sh/docs/python/reference/calendar#updateSubscription); Ruby [`calendar.update_subscription`](https://nextmail.sh/docs/ruby/reference/calendar#updateSubscription); PHP [`calendar->updateSubscription`](https://nextmail.sh/docs/php/reference/calendar#updateSubscription); Go [`Calendar.UpdateSubscription`](https://nextmail.sh/docs/go/reference/calendar#updateSubscription); Java [`calendar().updateSubscription`](https://nextmail.sh/docs/java/reference/calendar#updateSubscription); C# [`Calendar.UpdateSubscriptionAsync`](https://nextmail.sh/docs/csharp/reference/calendar#updateSubscription).

### `refreshCalendarSubscription`

Read a subscribed calendar again now, and restart one that stopped after failures.

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

**Inputs**

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

Also available in: API [`POST /calendar/subscriptions/{id}/refresh`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-subscriptions-id-refresh); TypeScript [`nextmail.calendar.refreshSubscription()`](https://nextmail.sh/docs/sdk/reference/calendar#refreshSubscription); Python [`calendar.refresh_subscription()`](https://nextmail.sh/docs/python/reference/calendar#refreshSubscription); Ruby [`calendar.refresh_subscription`](https://nextmail.sh/docs/ruby/reference/calendar#refreshSubscription); PHP [`calendar->refreshSubscription`](https://nextmail.sh/docs/php/reference/calendar#refreshSubscription); Go [`Calendar.RefreshSubscription`](https://nextmail.sh/docs/go/reference/calendar#refreshSubscription); Java [`calendar().refreshSubscription`](https://nextmail.sh/docs/java/reference/calendar#refreshSubscription); C# [`Calendar.RefreshSubscriptionAsync`](https://nextmail.sh/docs/csharp/reference/calendar#refreshSubscription).

### `unsubscribeFromCalendar`

Remove a calendar subscription and every event it brought onto your calendar. 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/subscriptions/{id}`](https://nextmail.sh/docs/api/reference/calendar#delete-calendar-subscriptions-id); TypeScript [`nextmail.calendar.deleteSubscription()`](https://nextmail.sh/docs/sdk/reference/calendar#deleteSubscription); Python [`calendar.delete_subscription()`](https://nextmail.sh/docs/python/reference/calendar#deleteSubscription); Ruby [`calendar.delete_subscription`](https://nextmail.sh/docs/ruby/reference/calendar#deleteSubscription); PHP [`calendar->deleteSubscription`](https://nextmail.sh/docs/php/reference/calendar#deleteSubscription); Go [`Calendar.DeleteSubscription`](https://nextmail.sh/docs/go/reference/calendar#deleteSubscription); Java [`calendar().deleteSubscription`](https://nextmail.sh/docs/java/reference/calendar#deleteSubscription); C# [`Calendar.DeleteSubscriptionAsync`](https://nextmail.sh/docs/csharp/reference/calendar#deleteSubscription).

### `listCalendarImports`

The calendar imports of this workspace, newest first, as Import in the Calendars dialog of the app lists them: an .ics file somebody uploaded, the calendars inside a Google Takeout archive, or the calendars pulled from an old mailbox. Each line says how many events it found, added, found already here and left out. A member sees their own. Uploading a file takes bytes a tool call does not carry, so that is done in the app, over the REST API or with the CLI. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

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

**Inputs**

- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /calendar/imports`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-imports); TypeScript [`nextmail.calendar.listImports()`](https://nextmail.sh/docs/sdk/reference/calendar#listImports), [`nextmail.calendar.listAllImports()`](https://nextmail.sh/docs/sdk/reference/calendar#listAllImports), [`nextmail.calendar.iterateImports()`](https://nextmail.sh/docs/sdk/reference/calendar#iterateImports); Python [`calendar.list_imports()`](https://nextmail.sh/docs/python/reference/calendar#listImports), [`calendar.list_all_imports()`](https://nextmail.sh/docs/python/reference/calendar#listAllImports), [`calendar.iterate_imports()`](https://nextmail.sh/docs/python/reference/calendar#iterateImports); Ruby [`calendar.list_imports`](https://nextmail.sh/docs/ruby/reference/calendar#listImports), [`calendar.list_all_imports`](https://nextmail.sh/docs/ruby/reference/calendar#listAllImports), [`calendar.iterate_imports`](https://nextmail.sh/docs/ruby/reference/calendar#iterateImports); PHP [`calendar->listImports`](https://nextmail.sh/docs/php/reference/calendar#listImports), [`calendar->listAllImports`](https://nextmail.sh/docs/php/reference/calendar#listAllImports), [`calendar->iterateImports`](https://nextmail.sh/docs/php/reference/calendar#iterateImports); Go [`Calendar.ListImports`](https://nextmail.sh/docs/go/reference/calendar#listImports), [`Calendar.ListAllImports`](https://nextmail.sh/docs/go/reference/calendar#listAllImports), [`Calendar.IterateImports`](https://nextmail.sh/docs/go/reference/calendar#iterateImports); Java [`calendar().listImports`](https://nextmail.sh/docs/java/reference/calendar#listImports), [`calendar().listAllImports`](https://nextmail.sh/docs/java/reference/calendar#listAllImports), [`calendar().iterateImports`](https://nextmail.sh/docs/java/reference/calendar#iterateImports); C# [`Calendar.ListImportsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listImports), [`Calendar.ListAllImportsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listAllImports), [`Calendar.IterateImportsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#iterateImports).

### `getCalendarImport`

One calendar import by its id, with its report: the calendars the file held and how many events each gave, how many were left out and why, and the first few that were not brought in. Imported events are ordinary events, and nobody invited to one was sent anything.

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

**Inputs**

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

Also available in: API [`GET /calendar/imports/{id}`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-imports-id); TypeScript [`nextmail.calendar.getImport()`](https://nextmail.sh/docs/sdk/reference/calendar#getImport); Python [`calendar.get_import()`](https://nextmail.sh/docs/python/reference/calendar#getImport); Ruby [`calendar.get_import`](https://nextmail.sh/docs/ruby/reference/calendar#getImport); PHP [`calendar->getImport`](https://nextmail.sh/docs/php/reference/calendar#getImport); Go [`Calendar.GetImport`](https://nextmail.sh/docs/go/reference/calendar#getImport); Java [`calendar().getImport`](https://nextmail.sh/docs/java/reference/calendar#getImport); C# [`Calendar.GetImportAsync`](https://nextmail.sh/docs/csharp/reference/calendar#getImport).

### `undoCalendarImport`

Remove every event one calendar import added, as Remove imported events does in the app. Events that were on the calendar before it stay, and nobody is told. It cannot be taken back, though the same file can be imported again. 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 [`POST /calendar/imports/{id}/undo`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-imports-id-undo); TypeScript [`nextmail.calendar.undoImport()`](https://nextmail.sh/docs/sdk/reference/calendar#undoImport); Python [`calendar.undo_import()`](https://nextmail.sh/docs/python/reference/calendar#undoImport); Ruby [`calendar.undo_import`](https://nextmail.sh/docs/ruby/reference/calendar#undoImport); PHP [`calendar->undoImport`](https://nextmail.sh/docs/php/reference/calendar#undoImport); Go [`Calendar.UndoImport`](https://nextmail.sh/docs/go/reference/calendar#undoImport); Java [`calendar().undoImport`](https://nextmail.sh/docs/java/reference/calendar#undoImport); C# [`Calendar.UndoImportAsync`](https://nextmail.sh/docs/csharp/reference/calendar#undoImport).

### `hideCalendarEvent`

Hide an event from your own calendar and leave it for everyone else, as Hide from my calendar does in the app, or put it back with hidden false. Use it for an invitation that reached you through a shared address, or an event you may not remove. Hiding also stops its reminders for you. A chat asks first unless you asked for it.

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

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `hidden` (`boolean`): false shows a hidden event again.

Also available in: API [`POST /calendar/events/{id}/hide`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events-id-hide), [`POST /calendar/events/{id}/unhide`](https://nextmail.sh/docs/api/reference/calendar#post-calendar-events-id-unhide); TypeScript [`nextmail.calendar.hideEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#hideEvent), [`nextmail.calendar.unhideEvent()`](https://nextmail.sh/docs/sdk/reference/calendar#unhideEvent); Python [`calendar.hide_event()`](https://nextmail.sh/docs/python/reference/calendar#hideEvent), [`calendar.unhide_event()`](https://nextmail.sh/docs/python/reference/calendar#unhideEvent); Ruby [`calendar.hide_event`](https://nextmail.sh/docs/ruby/reference/calendar#hideEvent), [`calendar.unhide_event`](https://nextmail.sh/docs/ruby/reference/calendar#unhideEvent); PHP [`calendar->hideEvent`](https://nextmail.sh/docs/php/reference/calendar#hideEvent), [`calendar->unhideEvent`](https://nextmail.sh/docs/php/reference/calendar#unhideEvent); Go [`Calendar.HideEvent`](https://nextmail.sh/docs/go/reference/calendar#hideEvent), [`Calendar.UnhideEvent`](https://nextmail.sh/docs/go/reference/calendar#unhideEvent); Java [`calendar().hideEvent`](https://nextmail.sh/docs/java/reference/calendar#hideEvent), [`calendar().unhideEvent`](https://nextmail.sh/docs/java/reference/calendar#unhideEvent); C# [`Calendar.HideEventAsync`](https://nextmail.sh/docs/csharp/reference/calendar#hideEvent), [`Calendar.UnhideEventAsync`](https://nextmail.sh/docs/csharp/reference/calendar#unhideEvent).

### `findMeetingTime`

When people are busy and the first times everyone is free, as Find a time in the event editor shows it. emails takes up to 20 addresses: one of the workspace shows the busy times of the person who holds it, and any other address is unknown. from and to are ISO 8601 with a zone, at most 31 days apart. With durationMinutes it suggests up to five times, on weekdays between 09:00 and 17:00 in timezone (UTC unless you say).

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

**Inputs**

- `emails` (`string[]`, required, 1 to 20 items)
- `from` (`string`, required, format `date-time`)
- `to` (`string`, required, format `date-time`)
- `timezone` (`string`, 1 to 64 characters)
- `durationMinutes` (`integer`, at least 5, at most 480)

Also available in: API [`GET /calendar/free-busy`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-free-busy); TypeScript [`nextmail.calendar.freeBusy()`](https://nextmail.sh/docs/sdk/reference/calendar#freeBusy); Python [`calendar.free_busy()`](https://nextmail.sh/docs/python/reference/calendar#freeBusy); Ruby [`calendar.free_busy`](https://nextmail.sh/docs/ruby/reference/calendar#freeBusy); PHP [`calendar->freeBusy`](https://nextmail.sh/docs/php/reference/calendar#freeBusy); Go [`Calendar.FreeBusy`](https://nextmail.sh/docs/go/reference/calendar#freeBusy); Java [`calendar().freeBusy`](https://nextmail.sh/docs/java/reference/calendar#freeBusy); C# [`Calendar.FreeBusyAsync`](https://nextmail.sh/docs/csharp/reference/calendar#freeBusy).