API reference

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.

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

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Query parameter	Type	Required	Default	Notes
`emails`	`string`	No	`""`	up to 4,000 characters
`self`	`"0" \| "1"`	No
`from`	`integer`	Yes		coerced from a string
`to`	`integer`	Yes		coerced from a string
`timeZone`	`string`	No		up to 64 characters
`excludeUid`	`string`	No		up to 1,000 characters

Response 200

{
  people: {
    email: string
    known: boolean
    busy: {
      start: number
      end: number
      status: "tentative" | "busy" | "oof" | "workingElsewhere"
    }[]
    self?: true
  }[]
}

Errors

Status	Message
`400`	Ask for at most 20 addresses at a time.
`400`	Ask for at least one address.
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:threadId`	Conversation id (`thr_…`), or in Mirage a thread id (`mth_…`).
`:messageId`	Message id (`msg_…`; Mirage messages are `mmg_…`).
`:action`	`add` (put the event in a calendar), `refresh` (send the guest who asked the latest version) or `counter` (answer a proposed new time).

Request body

Field	Type	Required	Notes
`calendarId`	`any JSON`	No
`accept`	`boolean`	No

Response 200

{
  notified: {
    sent: number
    error?: string
  }
}
| {
  notified: {
    sent: number
    error?: string
  }
  eventId: string
}

Response 201

{
  calendarId: string
  eventIds: string[]
}

Errors

Status	Message
`400`	Say whether to accept the proposal.
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`404`	Message not found
`404`	Not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Notes
`from`	`integer`	Yes	coerced from a string
`to`	`integer`	Yes	coerced from a string

Response 200

{
  events: {
    mailboxId: string
    calendarId: string
    calendarName: string
    eventId: string
    summary: string
    start: number
    end: number
    allDay: boolean
    startDate?: string
    endDate?: string
    location: string
  }[]
}

Errors

Status	Message
`400`	Choose a window of at most 62 days.

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars`

The mailbox's calendars, default first. The default calendar is created on first use.

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Response 200

{
  calendars: {
    calendarId: string
    name: string
    color: string
    description: string
    isDefault: boolean
    version: number
  }[]
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars`

Creates a calendar (at most 50 per mailbox).

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	Yes	1–100 characters; trimmed
`color`	`"blue" \| "orange" \| "teal" \| "amber" \| "pink" \| "green" \| "red" \| "gray"`	No
`description`	`string`	No	up to 1,000 characters

Response 201

{
  calendar: {
    calendarId: string
    name: string
    color: string
    description: string
    isDefault: boolean
    version: number
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

`PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId`

Renames a calendar or changes its color or description.

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`color`	`"blue" \| "orange" \| "teal" \| "amber" \| "pink" \| "green" \| "red" \| "gray"`	No
`description`	`string`	No	up to 1,000 characters

Response 200

{
  calendar: {
    calendarId: string
    name: string
    color: string
    description: string
    isDefault: boolean
    version: number
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId`

Deletes a calendar and its events. The default calendar can't be deleted.

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).

Response 204 with no body.

Errors

Status	Message
`400`	The default calendar can't be deleted.
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

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

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Query parameter	Type	Required	Notes
`from`	`integer`	Yes	coerced from a string
`to`	`integer`	Yes	coerced from a string
`calendarId`	`string`	No	up to 2,000 characters

Response 200

{
  occurrences: {
    eventId: string
    calendarId: string
    recurrenceId: number
    start: number
    end: number
    allDay: boolean
    startDate?: string
    endDate?: string
    summary: string
    location: string
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    recurring: boolean
    isException: boolean
    isOrganizer: boolean
    attendees: number
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    reminders: number[]
  }[]
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

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

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).

Query parameter	Type	Required	Notes
`q`	`string`	Yes	1–200 characters; trimmed

Response 200

{
  results: {
    eventId: string
    calendarId: string
    recurrenceId: number
    start: number
    end: number
    allDay: boolean
    startDate?: string
    endDate?: string
    summary: string
    location: string
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    recurring: boolean
    isException: boolean
    isOrganizer: boolean
    attendees: number
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    reminders: number[]
  }[]
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).

Request body

Field	Type	Required	Default	Notes
`summary`	`string`	No	`""`	up to 1,000 characters; trimmed
`description`	`string`	No		up to 64,000 characters
`location`	`string`	No		up to 2,000 characters
`allDay`	`boolean`	No	`false`
`start`	`string`	Yes		matches `^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?)?$`
`end`	`string`	Yes		matches `^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?)?$`
`timeZone`	`string`	Yes		1–64 characters
`recurrence`	`object`	No		can be `null`
`recurrence.freq`	`"daily" \| "weekly" \| "monthly" \| "yearly"`	Yes
`recurrence.interval`	`integer`	No	`1`	1–999
`recurrence.count`	`integer`	No		1–5000
`recurrence.until`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`
`recurrence.byDay`	`object[]`	No		up to 7 items
`recurrence.byDay[].day`	`"SU" \| "MO" \| "TU" \| "WE" \| "TH" \| "FR" \| "SA"`	Yes
`recurrence.byDay[].nth`	`integer`	No		-53–53
`recurrence.byMonthDay`	`integer[]`	No		up to 31 items; each -31–31
`recurrence.byMonth`	`integer[]`	No		up to 12 items; each 1–12
`recurrence.bySetPos`	`integer[]`	No		up to 10 items; each -366–366
`attendees`	`object[]`	No		up to 200 items
`attendees[].email`	`string`	Yes		trimmed; lowercased
`attendees[].name`	`string`	No		up to 200 characters; trimmed
`attendees[].optional`	`boolean`	No
`busyStatus`	`"free" \| "tentative" \| "busy" \| "oof" \| "workingElsewhere"`	No
`sensitivity`	`"normal" \| "personal" \| "private" \| "confidential"`	No
`reminders`	`integer[]`	No		up to 5 items; each -10080–40320
`categories`	`string[]`	No		up to 30 items; each 1–100 characters, trimmed
`url`	`string`	No		up to 2,000 characters; URL
`status`	`"confirmed" \| "tentative" \| "cancelled"`	No
`notify`	`boolean`	No	`true`

Response 201

{
  event: {
    eventId: string
    calendarId: string
    uid: string
    version: number
    summary: string
    description: string
    location: string
    allDay: boolean
    start: number
    end: number
    startLocal: string
    endLocal: string
    timeZone: string
    organizer: null | {
      email: string
      name?: string
    }
    attendees: {
      email: string
      name?: string
      role: "optional" | "required" | "chair" | "non-participant"
      status: "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      rsvp: boolean
      kind: "unknown" | "resource" | "group" | "individual" | "room"
      delegatedTo?: string[]
      delegatedFrom?: string[]
    }[]
    isOrganizer: boolean
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    sensitivity: "private" | "personal" | "normal" | "confidential"
    reminders: number[]
    categories: string[]
    url: null | string
    recurrence: null | {
      count?: number
      byDay?: {
        day: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
        nth?: number
      }[]
      interval: number
      weekStart?: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
      freq: "daily" | "weekly" | "monthly" | "yearly"
      byMonthDay?: number[]
      byMonth?: number[]
      bySetPos?: number[]
      until?: string
    }
    rrule: null | string
    exceptions: {
      recurrenceId: number
      start: number
      end: number
      startLocal: string
      endLocal: string
      summary: string
      location: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    }[]
    sequence: number
  }
  notified: {
    sent: number
    error?: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/events/:eventId`

An event with its recurrence, attendees, answers and changed occurrences.

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Response 200

{
  event: {
    eventId: string
    calendarId: string
    uid: string
    version: number
    summary: string
    description: string
    location: string
    allDay: boolean
    start: number
    end: number
    startLocal: string
    endLocal: string
    timeZone: string
    organizer: null | {
      email: string
      name?: string
    }
    attendees: {
      email: string
      name?: string
      role: "optional" | "required" | "chair" | "non-participant"
      status: "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      rsvp: boolean
      kind: "unknown" | "resource" | "group" | "individual" | "room"
      delegatedTo?: string[]
      delegatedFrom?: string[]
    }[]
    isOrganizer: boolean
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    sensitivity: "private" | "personal" | "normal" | "confidential"
    reminders: number[]
    categories: string[]
    url: null | string
    recurrence: null | {
      count?: number
      byDay?: {
        day: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
        nth?: number
      }[]
      interval: number
      weekStart?: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
      freq: "daily" | "weekly" | "monthly" | "yearly"
      byMonthDay?: number[]
      byMonth?: number[]
      bySetPos?: number[]
      until?: string
    }
    rrule: null | string
    exceptions: {
      recurrenceId: number
      start: number
      end: number
      startLocal: string
      endLocal: string
      summary: string
      location: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    }[]
    sequence: number
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Request body

Field	Type	Required	Default	Notes
`summary`	`string`	No	`""`	up to 1,000 characters; trimmed
`description`	`string`	No		up to 64,000 characters
`location`	`string`	No		up to 2,000 characters
`allDay`	`boolean`	No	`false`
`start`	`string`	Yes		matches `^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?)?$`
`end`	`string`	Yes		matches `^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?)?$`
`timeZone`	`string`	Yes		1–64 characters
`recurrence`	`object`	No		can be `null`
`recurrence.freq`	`"daily" \| "weekly" \| "monthly" \| "yearly"`	Yes
`recurrence.interval`	`integer`	No	`1`	1–999
`recurrence.count`	`integer`	No		1–5000
`recurrence.until`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`
`recurrence.byDay`	`object[]`	No		up to 7 items
`recurrence.byDay[].day`	`"SU" \| "MO" \| "TU" \| "WE" \| "TH" \| "FR" \| "SA"`	Yes
`recurrence.byDay[].nth`	`integer`	No		-53–53
`recurrence.byMonthDay`	`integer[]`	No		up to 31 items; each -31–31
`recurrence.byMonth`	`integer[]`	No		up to 12 items; each 1–12
`recurrence.bySetPos`	`integer[]`	No		up to 10 items; each -366–366
`attendees`	`object[]`	No		up to 200 items
`attendees[].email`	`string`	Yes		trimmed; lowercased
`attendees[].name`	`string`	No		up to 200 characters; trimmed
`attendees[].optional`	`boolean`	No
`busyStatus`	`"free" \| "tentative" \| "busy" \| "oof" \| "workingElsewhere"`	No
`sensitivity`	`"normal" \| "personal" \| "private" \| "confidential"`	No
`reminders`	`integer[]`	No		up to 5 items; each -10080–40320
`categories`	`string[]`	No		up to 30 items; each 1–100 characters, trimmed
`url`	`string`	No		up to 2,000 characters; URL
`status`	`"confirmed" \| "tentative" \| "cancelled"`	No
`notify`	`boolean`	No	`true`
`recurrenceId`	`integer`	No
`following`	`boolean`	No
`ifVersion`	`integer`	No		≥ 0
`moveTo`	`any JSON`	No

Response 200

{
  event: {
    eventId: string
    calendarId: string
    uid: string
    version: number
    summary: string
    description: string
    location: string
    allDay: boolean
    start: number
    end: number
    startLocal: string
    endLocal: string
    timeZone: string
    organizer: null | {
      email: string
      name?: string
    }
    attendees: {
      email: string
      name?: string
      role: "optional" | "required" | "chair" | "non-participant"
      status: "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      rsvp: boolean
      kind: "unknown" | "resource" | "group" | "individual" | "room"
      delegatedTo?: string[]
      delegatedFrom?: string[]
    }[]
    isOrganizer: boolean
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    sensitivity: "private" | "personal" | "normal" | "confidential"
    reminders: number[]
    categories: string[]
    url: null | string
    recurrence: null | {
      count?: number
      byDay?: {
        day: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
        nth?: number
      }[]
      interval: number
      weekStart?: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
      freq: "daily" | "weekly" | "monthly" | "yearly"
      byMonthDay?: number[]
      byMonth?: number[]
      bySetPos?: number[]
      until?: string
    }
    rrule: null | string
    exceptions: {
      recurrenceId: number
      start: number
      end: number
      startLocal: string
      endLocal: string
      summary: string
      location: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    }[]
    sequence: number
  }
  version: number
  notified: {
    sent: number
    error?: string
  }
  eventId?: string
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Query parameter	Type	Required	Default	Notes
`recurrenceId`	`integer`	No		coerced from a string
`following`	`"true" \| "false"`	No	`"false"`
`notify`	`"true" \| "false"`	No	`"true"`
`ifVersion`	`integer`	No		≥ 0; coerced from a string

Response 200

{
  notified: {
    sent: number
    error?: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Request body

Field	Type	Required	Default	Notes
`status`	`"accepted" \| "tentative" \| "declined"`	Yes
`recurrenceId`	`integer`	No
`comment`	`string`	No		up to 2,000 characters
`notify`	`boolean`	No	`true`

Response 200

{
  event: {
    eventId: string
    calendarId: string
    uid: string
    version: number
    summary: string
    description: string
    location: string
    allDay: boolean
    start: number
    end: number
    startLocal: string
    endLocal: string
    timeZone: string
    organizer: null | {
      email: string
      name?: string
    }
    attendees: {
      email: string
      name?: string
      role: "optional" | "required" | "chair" | "non-participant"
      status: "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      rsvp: boolean
      kind: "unknown" | "resource" | "group" | "individual" | "room"
      delegatedTo?: string[]
      delegatedFrom?: string[]
    }[]
    isOrganizer: boolean
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    sensitivity: "private" | "personal" | "normal" | "confidential"
    reminders: number[]
    categories: string[]
    url: null | string
    recurrence: null | {
      count?: number
      byDay?: {
        day: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
        nth?: number
      }[]
      interval: number
      weekStart?: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
      freq: "daily" | "weekly" | "monthly" | "yearly"
      byMonthDay?: number[]
      byMonth?: number[]
      bySetPos?: number[]
      until?: string
    }
    rrule: null | string
    exceptions: {
      recurrenceId: number
      start: number
      end: number
      startLocal: string
      endLocal: string
      summary: string
      location: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    }[]
    sequence: number
  }
  notified: {
    sent: number
    error?: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Request body

Field	Type	Required	Default	Notes
`to`	`object`	Yes
`to.email`	`string`	Yes		up to 254 characters; trimmed; lowercased
`to.name`	`string`	No		up to 200 characters; trimmed
`recurrenceId`	`integer`	No
`comment`	`string`	No		up to 2,000 characters
`notify`	`boolean`	No	`true`

Response 200

{
  event: {
    eventId: string
    calendarId: string
    uid: string
    version: number
    summary: string
    description: string
    location: string
    allDay: boolean
    start: number
    end: number
    startLocal: string
    endLocal: string
    timeZone: string
    organizer: null | {
      email: string
      name?: string
    }
    attendees: {
      email: string
      name?: string
      role: "optional" | "required" | "chair" | "non-participant"
      status: "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
      rsvp: boolean
      kind: "unknown" | "resource" | "group" | "individual" | "room"
      delegatedTo?: string[]
      delegatedFrom?: string[]
    }[]
    isOrganizer: boolean
    myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    status: "cancelled" | "confirmed" | "tentative"
    busyStatus: "free" | "tentative" | "busy" | "oof" | "workingElsewhere"
    sensitivity: "private" | "personal" | "normal" | "confidential"
    reminders: number[]
    categories: string[]
    url: null | string
    recurrence: null | {
      count?: number
      byDay?: {
        day: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
        nth?: number
      }[]
      interval: number
      weekStart?: "SA" | "SU" | "MO" | "TU" | "WE" | "TH" | "FR"
      freq: "daily" | "weekly" | "monthly" | "yearly"
      byMonthDay?: number[]
      byMonth?: number[]
      bySetPos?: number[]
      until?: string
    }
    rrule: null | string
    exceptions: {
      recurrenceId: number
      start: number
      end: number
      startLocal: string
      endLocal: string
      summary: string
      location: string
      status: "cancelled" | "confirmed" | "tentative"
      myStatus: null | "accepted" | "delegated" | "tentative" | "needs-action" | "declined"
    }[]
    sequence: number
  }
  notified: {
    sent: number
    error?: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).
`:eventId`	Event id: a calendar event (`evt_…`; a recurring event's occurrences share it), or a Mirage server's event (`mev_…`).

Request body

Field	Type	Required	Notes
`start`	`integer`	Yes
`end`	`integer`	Yes
`recurrenceId`	`integer`	No
`comment`	`string`	No	up to 2,000 characters

Response 200

{
  notified: {
    sent: number
    error?: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.

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

Auth: user access token or platform agent key · Scope: calendar:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).

Request body (up to 6 MB)

Field	Type	Required	Notes
`ics`	`string`	Yes	1–5,242,880 characters
`timeZone`	`string`	No	up to 64 characters

Response 200

{
  created: number
  updated: number
  skipped: number
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`409`	This mailbox's domain was removed.
`409`	… isn't verified for sending yet.
`413`	The file is too large (at most 5 MB).

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/calendars/:calendarId/export`

The calendar as an iCalendar file.

Auth: user access token or platform agent key · Scope: calendar:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:calendarId`	Calendar id (`cal_…`).

Response 200

{
  filename: string
  ics: string
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

Calendar

On this page