---
title: "nextmail calendar"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/calendar"
area: "CLI"
category: "Reference"
---

# nextmail calendar

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail calendar list-events`

List one page of event occurrences inside a time window

```bash
nextmail calendar list-events --from <when> --to <when> [flags]
```

Expands your events into their occurrences between `from` and `to` and returns one page of them, sorted by start time and then by event id. A recurring series gives one row per instance in the window, with its excluded dates left out, and every row points back to its event through `eventId`. The window is required because a repeating series has no end to list up to.

`to` must be after `from` and at most 366 days later. A missing `from` or `to` is a 422 `invalid_parameter`, while a value that does not parse, a reversed or overlong window, or an unknown zone is a 400 `invalid_parameter` naming the field. Both bounds take a `Date` or an ISO 8601 string, and the SDK converts a `Date` with `toISOString()`.

`timezone` is an IANA zone and defaults to `UTC` on the server. It is used to expand any event stored without a zone of its own, which is what decides the day an all day event lands on.

Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Flags**

- `--from <when>`: Start of the window. Required.
- `--to <when>`: End of the window, after `from` and at most 366 days later. Required.
- `--timezone <value>`: IANA zone such as `Europe/London`, at most 64 characters. Defaults to `UTC`.
- `--include-team` (default `false`): Adds the events of the rest of the workspace, apart from the ones marked private. Only a key of the workspace owner sees more with it. Defaults to `false`.
- `--q <value>`: Words to look for in the title, the place and the organiser, at most 200 characters. Only events that hold every word come back, so pass a long window to find an event by name, and the same `q` with every cursor.
- `--limit <n>` (default `25`): Occurrences per page, a whole number from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` of the previous page, sent with the same window. It is opaque, so never build one yourself.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

The required values only

```bash
nextmail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z
```

With optional flags

```bash
nextmail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --timezone Europe/London --limit 50
```

Walk every page and stop after 100 items

```bash
nextmail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --all --max 100
```

One JSON object per line when piped

```bash
nextmail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --all > calendar.ndjson
```

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); Python [`calendar.list_events()`](https://nextmail.sh/docs/python/reference/calendar#listEvents); Ruby [`calendar.list_events`](https://nextmail.sh/docs/ruby/reference/calendar#listEvents); PHP [`calendar->listEvents`](https://nextmail.sh/docs/php/reference/calendar#listEvents); Go [`Calendar.ListEvents`](https://nextmail.sh/docs/go/reference/calendar#listEvents); Java [`calendar().listEvents`](https://nextmail.sh/docs/java/reference/calendar#listEvents); C# [`Calendar.ListEventsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listEvents).

### `nextmail calendar get-event`

Read an event with its attendees

```bash
nextmail calendar get-event <id> [flags]
```

Returns a stored event with its attendees and their responses. What the server understood from the iCalendar data is structured here: `recurrence` holds the `RRULE` text, `exdates` the excluded instances, `organizer` the organiser and `alarms` the reminders as `{ minutesBefore, action }`. The raw iCalendar source is not included, and `getEventIcs` serves the event as a document.

`id` is the event id, the `eventId` on an occurrence, and not the iCalendar `uid`. A recurring series is one event however many occurrences it has, so `start` and `end` describe its first instance. `messageId` and `threadId` link the event to mail in the mailbox when there is any.

Attendees come back in the order they were added, each with `partstat`, `role`, `rsvp`, `cutype` and `respondedAt`. A narrowed key gets a 404 unless one of the addresses it covers organises the event or is on the attendee list, and a key that holds a whole domain covers every address on it.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1
```

Print the raw JSON

```bash
nextmail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json
```

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

### `nextmail calendar get-event-ics`

Download an event as an iCalendar document

```bash
nextmail calendar get-event-ics <id> [flags]
```

Resolves with the event serialised as an `.ics` document, as a raw string rather than parsed JSON. The server sends it as `text/calendar; charset=utf-8` with a download filename built from the event's `uid`, and the SDK requests that type and returns the body untouched.

The document declares `METHOD:PUBLISH`, and the content type carries no `method` parameter. That is deliberate: a `REQUEST` document makes a calendar client offer accept and decline and reply to the organiser, and this endpoint has no authority to invite anyone. Import it to show what the event currently is, not to send an invitation.

It holds one `VEVENT` with the attendees and their participation status, the recurrence rule, excluded dates and alarms. Lines end in CRLF and long lines are folded. `DTSTAMP` is the time of the request, so two downloads of an unchanged event differ on that line.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence.

**Flags**

- `-o, --out <file>`: Write the text to this file instead of printing it

**Examples**

```bash
nextmail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1
```

Save the file

```bash
nextmail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out event.ics
```

Also available in: API [`GET /calendar/events/{id}/ics`](https://nextmail.sh/docs/api/reference/calendar#get-calendar-events-id-ics); TypeScript [`nextmail.calendar.getEventIcs()`](https://nextmail.sh/docs/sdk/reference/calendar#getEventIcs); Python [`calendar.get_event_ics()`](https://nextmail.sh/docs/python/reference/calendar#getEventIcs); Ruby [`calendar.get_event_ics`](https://nextmail.sh/docs/ruby/reference/calendar#getEventIcs); PHP [`calendar->getEventIcs`](https://nextmail.sh/docs/php/reference/calendar#getEventIcs); Go [`Calendar.GetEventIcs`](https://nextmail.sh/docs/go/reference/calendar#getEventIcs); Java [`calendar().getEventIcs`](https://nextmail.sh/docs/java/reference/calendar#getEventIcs); C# [`Calendar.GetEventIcsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#getEventIcs).

### `nextmail calendar create-event`

Put an event on the calendar

```bash
nextmail calendar create-event --summary <value> --start <when> --end <when> [flags]
nextmail calendar create-event --data <json|@file|-> [flags]
```

Creates an event, as New event on the Calendar page of the app does. `start` and `end` take a `Date` or ISO 8601 with a zone, and `timezone` is the IANA zone the event belongs to, which decides what an all-day event means.

With `attendees`, an invitation goes to each of them by email from `from`, which has to be an address the key may send as, so the call also needs `emails:send`. Send `sendInvites: false` to keep it to your own calendar.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Flags**

- `--summary <value>`: The title, 1 to 255 characters. Required, here or in `--data`.
- `--start <when>`: When it starts, a `Date` or ISO 8601 with a zone. Required, here or in `--data`.
- `--end <when>`: When it ends, after `start` and at most two years later. Required, here or in `--data`.
- `--description <value>`: Notes about the event, up to 8,000 characters.
- `--location <value>`: Where it is: a room, an address or a link.
- `--url <value>`: A link that belongs to the event.
- `--meeting-url <value>`: The link to the video call, such as a Zoom, Meet or Teams address. The invitation carries it, so guests get a Join button in their calendar too.
- `--all-day`: Whether it fills whole days. `start` and `end` then mark the days.
- `--timezone <value>`: The IANA zone the event belongs to, `UTC` unless you say.
- `--recurrence <value>`: An RRULE such as `FREQ=WEEKLY;BYDAY=MO` when it repeats.
- `--attendees <json|@file|->`: Up to 200 people to invite, each `{ email, name?, optional? }`. JSON shaped as `Array<CalendarAttendeeInput>`, inline or from a file with @path.
- `--reminders <json|@file|->`: Up to five reminders, each `{ minutesBefore, action? }`. JSON shaped as `Array<CalendarReminderInput>`, inline or from a file with @path.
- `--transparency <value>`: `OPAQUE` shows you busy and `TRANSPARENT` free.
- `--visibility <value>`: `PUBLIC`, `PRIVATE` or `CONFIDENTIAL`.
- `--send-invites`: False keeps the change to your own calendar, and sends nothing.
- `--from <value>`: The address the invitations come from. It has to be one the key may send as.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

The required values only

```bash
nextmail calendar create-event --summary Planning --start 2026-10-12T09:00:00Z --end 2026-10-12T09:30:00Z
```

With optional flags

```bash
nextmail calendar create-event --summary Planning --start 2026-10-12T09:00:00Z --end 2026-10-12T09:30:00Z --from team@acme.com
```

Read the whole body from a JSON file

```bash
nextmail calendar create-event --data @calendar.json
```

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).

### `nextmail calendar update-event`

Change an event

```bash
nextmail calendar update-event <id> [flags]
```

Changes an event you organise. A field you leave out keeps its value, and `attendees` replaces the whole list. Everyone invited gets the updated invitation by email from `from`, so a change to an event with attendees needs `emails:send` too, unless `--send-invites` is false.

For a repeating event, `scope` says which dates change, as the app asks when you edit one date: `occurrence` changes only the date that starts at `--occurrence-start`, `following` that date and every one after it, and `series` all of them. With `following` the later dates become a new series with its own `id`, which is what comes back, and the old one ends the day before.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Flags**

- `--summary <value>`: The title, 1 to 255 characters.
- `--start <when>`: When it starts, a `Date` or ISO 8601 with a zone.
- `--end <when>`: When it ends, after `start` and at most two years later.
- `--description <value>`: Notes about the event, up to 8,000 characters.
- `--location <value>`: Where it is: a room, an address or a link.
- `--url <value>`: A link that belongs to the event.
- `--meeting-url <value>`: The link to the video call. An empty string takes it off.
- `--all-day`: Whether it fills whole days. `start` and `end` then mark the days.
- `--timezone <value>`: The IANA zone the event belongs to, `UTC` unless you say.
- `--recurrence <value>`: An RRULE such as `FREQ=WEEKLY;BYDAY=MO` when it repeats.
- `--attendees <json|@file|->`: Up to 200 people to invite, each `{ email, name?, optional? }`. It replaces the whole list. JSON shaped as `Array<CalendarAttendeeInput>`, inline or from a file with @path.
- `--reminders <json|@file|->`: Up to five reminders, each `{ minutesBefore, action? }`. JSON shaped as `Array<CalendarReminderInput>`, inline or from a file with @path.
- `--transparency <value>`: `OPAQUE` shows you busy and `TRANSPARENT` free.
- `--visibility <value>`: `PUBLIC`, `PRIVATE` or `CONFIDENTIAL`.
- `--send-invites`: False keeps the change to your own calendar, and sends nothing.
- `--from <value>`: The address the invitations come from. It has to be one the key may send as.
- `--scope <value>`: `occurrence`, `following` or `series`: which dates of a repeating event change. Left out, the change reaches the event or date the id names.
- `--occurrence-start <when>`: The start of the date you mean, as `listEvents` gives it. Needed with `occurrence` and `following`.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

With optional flags

```bash
nextmail calendar update-event cal_3f9a1c7e5b2d48a06c1e9f4b --start 2026-10-12T10:00:00Z --end 2026-10-12T10:30:00Z
```

Print the raw JSON

```bash
nextmail calendar update-event cal_3f9a1c7e5b2d48a06c1e9f4b --start 2026-10-12T10:00:00Z --end 2026-10-12T10:30:00Z --json
```

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).

### `nextmail calendar delete-event`

Remove an event from the calendar

```bash
nextmail calendar delete-event <id> [flags]
```

Removes an event for good, as Remove does in the app. Nobody else is told, so call off a meeting with others in it with `cancelEvent` instead. For a repeating event, `scope` `occurrence` with `--occurrence-start` removes one date, and `following` that date and every one after it.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Flags**

- `--scope <value>`: `occurrence`, `following` or `series`: which dates of a repeating event go.
- `--occurrence-start <when>`: The start of the date you mean, as `listEvents` gives it. Needed with `occurrence` and `following`.

**Examples**

The required values only

```bash
nextmail calendar delete-event cal_3f9a1c7e5b2d48a06c1e9f4b
```

With optional flags

```bash
nextmail calendar delete-event cal_3f9a1c7e5b2d48a06c1e9f4b --scope occurrence --occurrence-start 2026-10-19T09:00:00Z
```

Skip the confirmation, for scripts

```bash
nextmail calendar delete-event cal_3f9a1c7e5b2d48a06c1e9f4b --yes
```

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).

### `nextmail calendar cancel-event`

Call off a meeting

```bash
nextmail calendar cancel-event <id> [flags]
```

Cancels a meeting you organise, as Cancel meeting does in the app. It stays on the calendar with `status` `CANCELLED`, and everyone invited is told it is off by email from `from`, so a meeting with attendees also needs `emails:send`.

For a repeating meeting, `scope` `occurrence` with `--occurrence-start` calls off one date, and `following` that date and every one after it. Guests get the matching update.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Flags**

- `--from <value>`: The address the cancellation comes from. It has to be one the key may send as.
- `--scope <value>`: `occurrence`, `following` or `series`: which dates of a repeating meeting are called off.
- `--occurrence-start <when>`: The start of the date you mean, as `listEvents` gives it. Needed with `occurrence` and `following`.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

The required values only

```bash
nextmail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b
```

With optional flags

```bash
nextmail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b --from team@acme.com
```

Skip the confirmation, for scripts

```bash
nextmail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b --yes
```

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).

### `nextmail calendar respond-to-event`

Answer an invitation

```bash
nextmail calendar respond-to-event <id> --response <value> [flags]
nextmail calendar respond-to-event <id> --data <json|@file|-> [flags]
```

Accepts, declines or tentatively accepts an invitation, as the buttons of an invitation do in the app. The answer goes to the organiser by email from the invited address the key may send as, or from `--responding-as` when the invitation went to more than one of yours, so it needs `emails:send` as well.

- Scopes: `calendar:write`, `emails:send`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Flags**

- `--response <value>`: `ACCEPTED`, `DECLINED` or `TENTATIVE`. Required, here or in `--data`.
- `--responding-as <value>`: Which of your invited addresses answers, when there is more than one.
- `--proposed-start <when>`: A new start to propose with your answer, sent together with `--proposed-end`.
- `--proposed-end <when>`: The end of the proposed time.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

```bash
nextmail calendar respond-to-event cal_3f9a1c7e5b2d48a06c1e9f4b --response ACCEPTED
```

Read the whole body from a JSON file

```bash
nextmail calendar respond-to-event cal_3f9a1c7e5b2d48a06c1e9f4b --data @calendar.json
```

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).

### `nextmail calendar decline-proposal`

Decline a proposed time

```bash
nextmail calendar decline-proposal <id> --attendee <value> [flags]
nextmail calendar decline-proposal <id> --data <json|@file|-> [flags]
```

Keeps the original time of a meeting you organise after a guest proposed another one, as Decline in the proposal on the event does in the app. The guest is told by email from `from`, or from the organising address, so it needs `emails:send` as well. To take the proposed time instead, change the event with `updateEvent`.

- Scopes: `calendar:write`, `emails:send`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Flags**

- `--attendee <value>`: The guest whose proposal you decline, by email address. Required, here or in `--data`.
- `--from <value>`: The address the answer is sent from, when it is not the organising address.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

```bash
nextmail calendar decline-proposal cal_8d3f0a2b9c4e41f7a6b5c2d1 --attendee example
```

Read the whole body from a JSON file

```bash
nextmail calendar decline-proposal cal_8d3f0a2b9c4e41f7a6b5c2d1 --data @calendar.json
```

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).

### `nextmail calendar hide-event`

Hide an event from your calendar

```bash
nextmail calendar hide-event <id> [flags]
```

Takes an event off your own calendar and leaves it for everyone else, as Hide from my calendar does in the app. Use it for an invitation that reached you through a shared address, or an event you may not remove. It hides every date of a repeating event, and stops its reminders for you. `unhideEvent` brings it back.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar hide-event cal_3f9a1c7e5b2d48a06c1e9f4b
```

Print the raw JSON

```bash
nextmail calendar hide-event cal_3f9a1c7e5b2d48a06c1e9f4b --json
```

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

### `nextmail calendar unhide-event`

Show a hidden event again

```bash
nextmail calendar unhide-event <id> [flags]
```

Puts an event you hid back on your calendar, as Show on my calendar does on the invitation in the app.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar unhide-event cal_3f9a1c7e5b2d48a06c1e9f4b
```

Print the raw JSON

```bash
nextmail calendar unhide-event cal_3f9a1c7e5b2d48a06c1e9f4b --json
```

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

### `nextmail calendar free-busy`

Free and busy times

```bash
nextmail calendar free-busy --emails <a,b> --from <when> --to <when> [flags]
```

When the people you name are busy, as Find a time in the event editor of the app shows it. An address of the workspace shows the busy times of the person who holds it, from their events, the invitations they have not declined, their subscribed calendars and their bookings, without any detail. Any other address comes back with `known` false.

With `--duration-minutes`, `suggestions` lists up to five times when everyone known is free, on weekdays between 09:00 and 17:00 in `timezone`. `from` and `to` take a `Date` or an ISO 8601 string and may be at most 31 days apart.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Flags**

- `--emails <a,b>` (repeatable): The addresses to look up, at most 20. Required.
- `--from <when>`: The start of the window. Required.
- `--to <when>`: The end of the window, at most 31 days after `from`. Required.
- `--timezone <value>` (default `"UTC"`): The IANA zone the suggested times keep to working hours in, `UTC` unless you say.
- `--duration-minutes <n>`: The length of the meeting, 5 to 480 minutes. Send it to get `suggestions`.

**Examples**

The required values only

```bash
nextmail calendar free-busy --emails ana@acme.com,ben@acme.com --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z
```

With optional flags

```bash
nextmail calendar free-busy --emails ana@acme.com,ben@acme.com --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --timezone Europe/London --duration-minutes 30
```

Print the raw JSON

```bash
nextmail calendar free-busy --emails ana@acme.com,ben@acme.com --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z --json
```

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).

### `nextmail calendar list-feeds`

List calendar links

```bash
nextmail calendar list-feeds [flags]
```

Resolves the secret links that publish your calendar to other calendar apps, as Share in the calendar settings of the app lists them. Anyone with a link can read what it shows, so treat `url` and `webcalUrl` like passwords.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Examples**

```bash
nextmail calendar list-feeds
```

Print the raw JSON

```bash
nextmail calendar list-feeds --json
```

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).

### `nextmail calendar create-feed`

Create a calendar link

```bash
nextmail calendar create-feed --name <value> --mode <value> [flags]
nextmail calendar create-feed --data <json|@file|-> [flags]
```

Makes a secret link that publishes your calendar as an iCalendar feed, for Google Calendar (From URL), Outlook (Subscribe from web) or Apple Calendar (New subscription). `full` shows every detail, `busy` only the times you are busy. The calendar app reads the link again on its own schedule, usually every few hours.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Flags**

- `--name <value>`: The name calendar apps show for the calendar, up to 100 characters. Required, here or in `--data`.
- `--mode <value>`: `full` for every detail, `busy` for busy times only. Required, here or in `--data`.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

```bash
nextmail calendar create-feed --name 'Work (busy)' --mode busy
```

Read the whole body from a JSON file

```bash
nextmail calendar create-feed --data @calendar.json
```

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).

### `nextmail calendar reset-feed`

Reset a calendar link

```bash
nextmail calendar reset-feed <id> [flags]
```

Replaces the secret in a calendar link, so the old address stops working everywhere it was shared. Paste the new address into the calendar apps you still want to update.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Calendar link id, `cfd_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar reset-feed cfd_3f9a1c7e5b2d48a06c1e9f4b
```

Skip the confirmation, for scripts

```bash
nextmail calendar reset-feed cfd_3f9a1c7e5b2d48a06c1e9f4b --yes
```

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).

### `nextmail calendar delete-feed`

Delete a calendar link

```bash
nextmail calendar delete-feed <id> [flags]
```

Turns a calendar link off for good. Calendar apps that subscribed to it stop getting updates.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Calendar link id, `cfd_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar delete-feed cfd_3f9a1c7e5b2d48a06c1e9f4b
```

Skip the confirmation, for scripts

```bash
nextmail calendar delete-feed cfd_3f9a1c7e5b2d48a06c1e9f4b --yes
```

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).

### `nextmail calendar list-subscriptions`

List calendar subscriptions

```bash
nextmail calendar list-subscriptions [flags]
```

Resolves the other calendars you subscribe to by link, such as a Google or Outlook calendar address, a team rota or public holidays, as Other calendars in the app lists them. Their events show on your calendar, read-only.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Examples**

```bash
nextmail calendar list-subscriptions
```

Print the raw JSON

```bash
nextmail calendar list-subscriptions --json
```

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).

### `nextmail calendar create-subscription`

Subscribe to a calendar

```bash
nextmail calendar create-subscription --url <value> [flags]
nextmail calendar create-subscription --data <json|@file|-> [flags]
```

Adds a calendar by its iCalendar link: an `https`, `http` or `webcal` address, such as the secret address of a Google calendar or a published Outlook calendar. It is read at once, then again about every half hour. `name` defaults to the name the calendar gives itself.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Flags**

- `--url <value>`: The calendar link, `https`, `http` or `webcal`. Required, here or in `--data`.
- `--name <value>`: The name to show, up to 100 characters.
- `--body-color <value>`: The colour of its events, from `CALENDAR_COLORS`.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

The required values only

```bash
nextmail calendar create-subscription --url webcal://example.com/holidays.ics
```

With optional flags

```bash
nextmail calendar create-subscription --url webcal://example.com/holidays.ics --body-color green
```

Read the whole body from a JSON file

```bash
nextmail calendar create-subscription --data @calendar.json
```

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).

### `nextmail calendar update-subscription`

Change a calendar subscription

```bash
nextmail calendar update-subscription <id> [flags]
```

Renames a subscription or gives it another colour.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Subscription id, `csb_` followed by 24 hex characters.

**Flags**

- `--name <value>`: The new name, up to 100 characters.
- `--patch-color <value>`: The new colour, from `CALENDAR_COLORS`.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

With optional flags

```bash
nextmail calendar update-subscription csb_3f9a1c7e5b2d48a06c1e9f4b --name 'Team rota' --patch-color purple
```

Print the raw JSON

```bash
nextmail calendar update-subscription csb_3f9a1c7e5b2d48a06c1e9f4b --name 'Team rota' --patch-color purple --json
```

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).

### `nextmail calendar refresh-subscription`

Refresh a calendar subscription

```bash
nextmail calendar refresh-subscription <id> [flags]
```

Reads a subscribed calendar again now instead of waiting for the next half-hourly read, and restarts one that stopped after repeated failures.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Subscription id, `csb_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar refresh-subscription csb_3f9a1c7e5b2d48a06c1e9f4b
```

Print the raw JSON

```bash
nextmail calendar refresh-subscription csb_3f9a1c7e5b2d48a06c1e9f4b --json
```

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).

### `nextmail calendar delete-subscription`

Unsubscribe from a calendar

```bash
nextmail calendar delete-subscription <id> [flags]
```

Removes a subscription and every event it brought onto your calendar.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Subscription id, `csb_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar delete-subscription csb_3f9a1c7e5b2d48a06c1e9f4b
```

Skip the confirmation, for scripts

```bash
nextmail calendar delete-subscription csb_3f9a1c7e5b2d48a06c1e9f4b --yes
```

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).

### `nextmail calendar import-ics`

Import a calendar file

```bash
nextmail calendar import-ics <data> [flags]
```

Sends an iCalendar (.ics) file as the request body and queues it. Its events become events of your own that you can edit, and nobody on them is sent anything, now or when you change them later, unless you ask for that on the change. Poll `getImport` until `status` is `completed`.

The file may be 10 MB and hold 25,000 events. Several calendars in one file are merged, and the report keeps their names. An event whose UID is already in the workspace is skipped and counted, never overwritten, so sending the same file twice adds nothing.

`data` is a `Blob`, an `ArrayBuffer` or a `Uint8Array`, and it goes out as `text/calendar`.

- Scopes: `calendar:write`.
- Needs a sign-in.

**Arguments**

- `<data>` (required): The .ics file: a `Blob`, `ArrayBuffer` or `Uint8Array`.

**Flags**

- `--filename <value>`: The name to show for the file in the list of imports, at most 255 characters.

**Examples**

The required values only

```bash
nextmail calendar import-ics ./calendar.ics
```

With optional flags

```bash
nextmail calendar import-ics ./calendar.ics --filename work.ics
```

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

### `nextmail calendar list-imports`

List calendar imports

```bash
nextmail calendar list-imports [flags]
```

Returns one page of the calendar files and calendars brought in, newest first, each with what it added and what it left out. Beside the files sent with `importIcs` it lists the calendars that came with a mailbox import, and those carry the id of that import in `parentImportId`.

Paging is keyset. `--limit` takes 1 to 100 and defaults to 25, and `nextCursor` goes back as `--cursor` while `hasMore` is true.

Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max <n>` stops after that many items.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Flags**

- `--limit <n>` (default `25`): Imports per page, a whole number from 1 to 100. The server defaults to 25.
- `--cursor <value>`: The `nextCursor` from the previous page. Never build one yourself.
- `--all`: Fetch every page and stream the items as they arrive.
- `--max <n>`: Stop after this many items. Implies `--all`.
- `--ndjson`: Print every item as one JSON object per line. Implies `--all`

**Examples**

```bash
nextmail calendar list-imports
```

With optional flags

```bash
nextmail calendar list-imports --limit 50
```

Walk every page and stop after 100 items

```bash
nextmail calendar list-imports --all --max 100
```

One JSON object per line when piped

```bash
nextmail calendar list-imports --all > calendar.ndjson
```

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); Python [`calendar.list_imports()`](https://nextmail.sh/docs/python/reference/calendar#listImports); Ruby [`calendar.list_imports`](https://nextmail.sh/docs/ruby/reference/calendar#listImports); PHP [`calendar->listImports`](https://nextmail.sh/docs/php/reference/calendar#listImports); Go [`Calendar.ListImports`](https://nextmail.sh/docs/go/reference/calendar#listImports); Java [`calendar().listImports`](https://nextmail.sh/docs/java/reference/calendar#listImports); C# [`Calendar.ListImportsAsync`](https://nextmail.sh/docs/csharp/reference/calendar#listImports).

### `nextmail calendar get-import`

Get a calendar import

```bash
nextmail calendar get-import <id> [flags]
```

Resolves one calendar import with its counts and its report: the calendars it read, how many events it left out and why, and up to 20 of the events it left out. Poll it after `importIcs` until `status` is `completed` or `failed`.

`counts.imported` is what was added and `counts.skipped` what was left out, which `report.skipped` breaks down by reason: `uid-taken` for an event that was already here, `no-start` for one with no start time, `invalid` for one that could not be read and `empty` for a file or calendar that held no events.

- Scopes: `calendar:read`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Calendar import id, `iimp_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar get-import iimp_3f9c2a7b1e4d8f60a5c7b92d
```

Print the raw JSON

```bash
nextmail calendar get-import iimp_3f9c2a7b1e4d8f60a5c7b92d --json
```

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).

### `nextmail calendar undo-import`

Remove what a calendar import added

```bash
nextmail calendar undo-import <id> [flags]
```

Deletes every event the import added, changed since or not, and marks the import `undone`. Nobody is told. Events that were skipped because they were already here are not touched.

- Scopes: `calendar:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Calendar import id, `iimp_` followed by 24 hex characters.

**Examples**

```bash
nextmail calendar undo-import iimp_3f9c2a7b1e4d8f60a5c7b92d
```

Skip the confirmation, for scripts

```bash
nextmail calendar undo-import iimp_3f9c2a7b1e4d8f60a5c7b92d --yes
```

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).