--- title: "openemail calendar" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://openemail.uk/docs/cli/reference/calendar" area: "CLI" category: "Reference" --- # openemail calendar Every command in this namespace, with its arguments, flags and examples. ## Commands ### `openemail calendar list-events` List one page of event occurrences inside a time window ```bash openemail calendar list-events --from --to [flags] ``` Expands every event in the workspace into its 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 ` stops after that many items. - Scopes: `calendar:read`. - Needs a sign-in. **Flags** - `--from `: Start of the window. Required. - `--to `: End of the window, after `from` and at most 366 days later. Required. - `--timezone `: IANA zone such as `Europe/London`, at most 64 characters. Defaults to `UTC`. - `--limit ` (default `25`): Occurrences per page, a whole number from 1 to 100. The server defaults to 25. - `--cursor `: 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 `: 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 openemail calendar list-events --from 2026-10-01T00:00:00Z --to 2026-10-31T23:59:59Z ``` With optional flags ```bash openemail 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 openemail 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 openemail 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://openemail.uk/docs/api/reference/calendar#get-calendar-events); SDK [`calendar.listEvents()`](https://openemail.uk/docs/sdk/reference/calendar#listEvents). ### `openemail calendar get-event` Read an event with its attendees ```bash openemail calendar get-event [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** - `` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters. **Examples** ```bash openemail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 ``` Print the raw JSON ```bash openemail calendar get-event cal_8d3f0a2b9c4e41f7a6b5c2d1 --json ``` Also available in: API [`GET /calendar/events/{id}`](https://openemail.uk/docs/api/reference/calendar#get-calendar-events-id); SDK [`calendar.getEvent()`](https://openemail.uk/docs/sdk/reference/calendar#getEvent). ### `openemail calendar get-event-ics` Download an event as an iCalendar document ```bash openemail calendar get-event-ics [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** - `` (required): Event id, the `eventId` of an occurrence. **Flags** - `-o, --out `: Write the text to this file instead of printing it **Examples** ```bash openemail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 ``` Save the file ```bash openemail calendar get-event-ics cal_8d3f0a2b9c4e41f7a6b5c2d1 --out event.ics ``` Also available in: API [`GET /calendar/events/{id}/ics`](https://openemail.uk/docs/api/reference/calendar#get-calendar-events-id-ics); SDK [`calendar.getEventIcs()`](https://openemail.uk/docs/sdk/reference/calendar#getEventIcs). ### `openemail calendar create-event` Put an event on the calendar ```bash openemail calendar create-event --summary --start --end [flags] openemail calendar create-event --data [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 `: The title, 1 to 255 characters. Required, here or in `--data`. - `--start `: When it starts, a `Date` or ISO 8601 with a zone. Required, here or in `--data`. - `--end `: When it ends, after `start` and at most two years later. Required, here or in `--data`. - `--description `: Notes about the event, up to 8,000 characters. - `--location `: Where it is: a room, an address or a link. - `--url `: A link that belongs to the event. - `--all-day`: Whether it fills whole days. `start` and `end` then mark the days. - `--timezone `: The IANA zone the event belongs to, `UTC` unless you say. - `--recurrence `: An RRULE such as `FREQ=WEEKLY;BYDAY=MO` when it repeats. - `--attendees `: Up to 200 people to invite, each `{ email, name?, optional? }`. JSON shaped as `Array`, inline or from a file with @path. - `--reminders `: Up to five reminders, each `{ minutesBefore, action? }`. JSON shaped as `Array`, inline or from a file with @path. - `--transparency `: `OPAQUE` shows you busy and `TRANSPARENT` free. - `--visibility `: `PUBLIC`, `PRIVATE` or `CONFIDENTIAL`. - `--send-invites`: False keeps the change to your own calendar, and sends nothing. - `--from `: The address the invitations come from. It has to be one the key may send as. - `--data `: 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 openemail calendar create-event --summary Planning --start 2026-10-12T09:00:00Z --end 2026-10-12T09:30:00Z ``` With optional flags ```bash openemail 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 openemail calendar create-event --data @calendar.json ``` Also available in: API [`POST /calendar/events`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events); SDK [`calendar.createEvent()`](https://openemail.uk/docs/sdk/reference/calendar#createEvent). ### `openemail calendar update-event` Change an event ```bash openemail calendar update-event [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. - Scopes: `calendar:write`. - Needs a sign-in. **Arguments** - `` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters. **Flags** - `--summary `: The title, 1 to 255 characters. - `--start `: When it starts, a `Date` or ISO 8601 with a zone. - `--end `: When it ends, after `start` and at most two years later. - `--description `: Notes about the event, up to 8,000 characters. - `--location `: Where it is: a room, an address or a link. - `--url `: A link that belongs to the event. - `--all-day`: Whether it fills whole days. `start` and `end` then mark the days. - `--timezone `: The IANA zone the event belongs to, `UTC` unless you say. - `--recurrence `: An RRULE such as `FREQ=WEEKLY;BYDAY=MO` when it repeats. - `--attendees `: Up to 200 people to invite, each `{ email, name?, optional? }`. It replaces the whole list. JSON shaped as `Array`, inline or from a file with @path. - `--reminders `: Up to five reminders, each `{ minutesBefore, action? }`. JSON shaped as `Array`, inline or from a file with @path. - `--transparency `: `OPAQUE` shows you busy and `TRANSPARENT` free. - `--visibility `: `PUBLIC`, `PRIVATE` or `CONFIDENTIAL`. - `--send-invites`: False keeps the change to your own calendar, and sends nothing. - `--from `: The address the invitations come from. It has to be one the key may send as. - `--data `: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash openemail calendar update-event cal_3f9a1c7e5b2d48a06c1e9f4b --start 2026-10-12T10:00:00Z --end 2026-10-12T10:30:00Z ``` Print the raw JSON ```bash openemail 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://openemail.uk/docs/api/reference/calendar#patch-calendar-events-id); SDK [`calendar.updateEvent()`](https://openemail.uk/docs/sdk/reference/calendar#updateEvent). ### `openemail calendar delete-event` Remove an event from the calendar ```bash openemail calendar delete-event [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. - Scopes: `calendar:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters. **Examples** ```bash openemail calendar delete-event cal_3f9a1c7e5b2d48a06c1e9f4b ``` Skip the confirmation, for scripts ```bash openemail calendar delete-event cal_3f9a1c7e5b2d48a06c1e9f4b --yes ``` Also available in: API [`DELETE /calendar/events/{id}`](https://openemail.uk/docs/api/reference/calendar#delete-calendar-events-id); SDK [`calendar.deleteEvent()`](https://openemail.uk/docs/sdk/reference/calendar#deleteEvent). ### `openemail calendar cancel-event` Call off a meeting ```bash openemail calendar cancel-event [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`. - Scopes: `calendar:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters. **Flags** - `--from `: The address the cancellation comes from. It has to be one the key may send as. - `--data `: 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 openemail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b ``` With optional flags ```bash openemail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b --from team@acme.com ``` Skip the confirmation, for scripts ```bash openemail calendar cancel-event cal_3f9a1c7e5b2d48a06c1e9f4b --yes ``` Also available in: API [`POST /calendar/events/{id}/cancel`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events-id-cancel); SDK [`calendar.cancelEvent()`](https://openemail.uk/docs/sdk/reference/calendar#cancelEvent). ### `openemail calendar respond-to-event` Answer an invitation ```bash openemail calendar respond-to-event --response [flags] openemail calendar respond-to-event --data [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** - `` (required): Event id, the `eventId` of an occurrence, such as `cal_` followed by 24 hex characters. **Flags** - `--response `: `ACCEPTED`, `DECLINED` or `TENTATIVE`. Required, here or in `--data`. - `--responding-as `: Which of your invited addresses answers, when there is more than one. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash openemail calendar respond-to-event cal_3f9a1c7e5b2d48a06c1e9f4b --response ACCEPTED ``` Read the whole body from a JSON file ```bash openemail calendar respond-to-event cal_3f9a1c7e5b2d48a06c1e9f4b --data @calendar.json ``` Also available in: API [`POST /calendar/events/{id}/respond`](https://openemail.uk/docs/api/reference/calendar#post-calendar-events-id-respond); SDK [`calendar.respondToEvent()`](https://openemail.uk/docs/sdk/reference/calendar#respondToEvent).