API

Calendar

Calendars, events, invitations and iCalendar import and export for the mailboxes you belong to.

These routes act only on mailboxes the signed-in person is a member of; keys get no mailboxes. Times in requests are wall-clock times in the event's timeZone; times in responses are UTC milliseconds, with the event's own wall-clock times alongside. See Calendar.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/availability`	Free/busy of other mailboxes in the organization (times and busy status only, no titles), for scheduling. Addresses outside the organization come back as unknown.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/threads/:threadId/messages/:messageId/invitation/:action`	Acts on the event a message carries: `add` puts a published or forwarded event in a calendar, `refresh` sends a guest who asked the latest version, `counter` accepts or declines a guest's proposed new time (the organizer only).
`GET /v1/orgs/:orgId/mail/calendar/mine`	The caller's own events across the mailboxes they're a member of (at most 62 days), read-only: what other apps show next to their own dates (the Tasks calendar's "My calendar"). Cancelled events and free time are left out.
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars`	The mailbox's calendars, default first. The default calendar is created on first use.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars`	Creates a calendar (at most 50 per mailbox).
`PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId`	Renames a calendar or changes its color or description.
`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId`	Deletes a calendar and its events. The default calendar can't be deleted.
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/events`	Occurrences between `from` and `to` (UTC milliseconds, at most 400 days apart) across the mailbox's calendars, or those in `calendarId` (comma-separated), with recurring events expanded in their own time zone.
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/events/search`	Occurrences whose title or location has every word of `q` (case and accents ignored), from a year back to two years ahead: upcoming first (soonest first), then earlier ones (latest first), one per event series, at most 50.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events`	Creates an event. Times are wall-clock times in `timeZone`; all-day events take dates with an exclusive end. With attendees, the mailbox is the organizer and, unless `notify` is false, attendees are emailed an invitation.
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId`	An event with its recurrence, attendees, answers and changed occurrences.
`PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId`	Updates an event, or with `recurrenceId` one occurrence of it. Changing a series' time or repeat rule drops its changed occurrences and asks attendees again. Attendees get the update; removed attendees get a cancellation. `moveTo` moves the event to another calendar.
`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId`	Deletes an event, or with `recurrenceId` one occurrence. Attendees of an event the mailbox organizes get a cancellation unless `notify=false`.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId/respond`	Accepts, tentatively accepts or declines an invitation (or one occurrence) and, unless `notify` is false, emails the answer to the organizer.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId/delegate`	Hands this mailbox's invitation to someone else (they're invited, the organizer is told).
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId/propose`	Proposes a new time to the organizer (COUNTER); nothing changes until they answer.
`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/import`	Adds the events in an iCalendar file; events whose UID is already in the calendar are replaced. Floating times are read in `timeZone`.
`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/export`	The calendar as an iCalendar file.