API reference

Contacts

Address books, contacts, photos and vCard 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. See Contacts.

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books`

The mailbox's address books, default first. The default address book is created on first use.

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

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

Response 200

{
  addressBooks: {
    addressBookId: string
    name: 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/address-books`

Creates an address book (at most 20 per mailbox).

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

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

Request body

Field	Type	Required	Notes
`name`	`any JSON`	Yes

Response 201

{
  addressBook: {
    addressBookId: string
    name: 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/address-books/:addressBookId`

Renames an address book.

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

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

Request body

Field	Type	Required	Notes
`name`	`any JSON`	Yes

Response 200

{
  addressBook: {
    addressBookId: string
    name: 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/address-books/:addressBookId`

Deletes an address book and its contacts. The default address book can't be deleted.

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

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

Response 204 with no body.

Errors

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

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

Contacts by name across the mailbox's address books, or one. q matches names, emails, phone numbers and organizations; every word must match. Pages with cursor.

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

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

Query parameter	Type	Required	Notes
`q`	`string`	No	up to 200 characters
`addressBookId`	`string`	No	up to 40 characters
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–500; coerced from a string

Response 200

{
  contacts: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }[]
  cursor: null | string
}

Errors

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

`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts`

Creates a contact. It needs a name, organization, email or phone number.

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

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

Request body

Field	Type	Required	Default	Notes
`fullName`	`any JSON`	No
`name`	`object`	No
`name.family`	`any JSON`	No	`""`
`name.given`	`any JSON`	No	`""`
`name.additional`	`any JSON`	No	`""`
`name.prefix`	`any JSON`	No	`""`
`name.suffix`	`any JSON`	No	`""`
`nickname`	`any JSON`	No
`emails`	`any JSON`	No
`phones`	`any JSON`	No
`addresses`	`object[]`	No		up to 10 items
`addresses[].type`	`"home" \| "work" \| "other"`	No	`"home"`
`addresses[].poBox`	`any JSON`	No	`""`
`addresses[].extended`	`any JSON`	No	`""`
`addresses[].street`	`any JSON`	No	`""`
`addresses[].locality`	`any JSON`	No	`""`
`addresses[].region`	`any JSON`	No	`""`
`addresses[].postalCode`	`any JSON`	No	`""`
`addresses[].country`	`any JSON`	No	`""`
`urls`	`any JSON`	No
`organization`	`any JSON`	No
`department`	`any JSON`	No
`title`	`any JSON`	No
`birthday`	`string`	No		matches `^(\d{4}\|-)-\d{2}-\d{2}$\|^$`
`anniversary`	`string`	No		matches `^(\d{4}\|-)-\d{2}-\d{2}$\|^$`
`notes`	`string`	No		up to 32,000 characters
`categories`	`any JSON[]`	No		up to 30 items

Response 201

{
  contact: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }
}

Errors

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

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId`

A contact.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Response 200

{
  contact: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }
}

Errors

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

`PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId`

Changes a contact. Fields left out keep their value; an empty birthday or anniversary clears it.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Request body

Field	Type	Required	Default	Notes
`fullName`	`any JSON`	No
`name`	`object`	No
`name.family`	`any JSON`	No	`""`
`name.given`	`any JSON`	No	`""`
`name.additional`	`any JSON`	No	`""`
`name.prefix`	`any JSON`	No	`""`
`name.suffix`	`any JSON`	No	`""`
`nickname`	`any JSON`	No
`emails`	`any JSON`	No
`phones`	`any JSON`	No
`addresses`	`object[]`	No		up to 10 items
`addresses[].type`	`"home" \| "work" \| "other"`	No	`"home"`
`addresses[].poBox`	`any JSON`	No	`""`
`addresses[].extended`	`any JSON`	No	`""`
`addresses[].street`	`any JSON`	No	`""`
`addresses[].locality`	`any JSON`	No	`""`
`addresses[].region`	`any JSON`	No	`""`
`addresses[].postalCode`	`any JSON`	No	`""`
`addresses[].country`	`any JSON`	No	`""`
`urls`	`any JSON`	No
`organization`	`any JSON`	No
`department`	`any JSON`	No
`title`	`any JSON`	No
`birthday`	`string`	No		matches `^(\d{4}\|-)-\d{2}-\d{2}$\|^$`
`anniversary`	`string`	No		matches `^(\d{4}\|-)-\d{2}-\d{2}$\|^$`
`notes`	`string`	No		up to 32,000 characters
`categories`	`any JSON[]`	No		up to 30 items
`ifVersion`	`integer`	No		≥ 0

Response 200

{
  contact: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }
}

Errors

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

`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId`

Deletes a contact and its photo.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Response 204 with no body.

Errors

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

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo`

A short-lived link to the contact's photo.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Response 200

{
  url: string
}

Errors

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

`PUT /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo`

Sets the contact's photo: a JPEG, PNG, GIF or WebP image of at most 1 MB, base64-encoded.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Request body (up to 2 MB)

Field	Type	Required	Notes
`contentType`	`"image/jpeg" \| "image/png" \| "image/gif" \| "image/webp"`	Yes
`data`	`string`	Yes	at least 1 character

Response 200

{
  contact: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`413`	Photos can be at most 1 MB.

`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/contacts/:contactId/photo`

Removes the contact's photo.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:addressBookId`	Address book id (`abk_…`).
`:contactId`	Contact id (`ctc_…`).

Response 200

{
  contact: {
    hasPhoto: boolean
    updatedAt: number
    uid: string
    fullName: string
    name: {
      family: string
      given: string
      additional: string
      prefix: string
      suffix: string
    }
    nickname: string
    emails: {
      value: string
      type: string
      pref?: boolean
    }[]
    phones: {
      value: string
      type: string
      pref?: boolean
    }[]
    addresses: {
      type: string
      poBox: string
      extended: string
      street: string
      locality: string
      region: string
      postalCode: string
      country: string
    }[]
    urls: {
      value: string
      type: string
      pref?: boolean
    }[]
    organization: string
    department: string
    title: string
    birthday?: string
    anniversary?: string
    notes: string
    categories: string[]
    contactId: string
    addressBookId: string
    version: number
    displayName: string
  }
}

Errors

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

`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/import`

Adds the contacts in a vCard file (3.0 or 4.0), photos included; contacts whose UID is already in the address book are replaced.

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

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

Request body (up to 6 MB)

Field	Type	Required	Notes
`vcf`	`string`	Yes	1–5,242,880 characters

Response 200

{
  created: number
  updated: number
  skipped: number
}

Errors

Status	Message
`403`	Mailboxes are only available to members.
`404`	Mailbox not found
`413`	The file is too large (at most 5 MB).

`GET /v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId/export`

The address book as a vCard file, version 4.0 or 3.0.

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

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

Query parameter	Type	Required	Default	Notes
`version`	`"3.0" \| "4.0"`	No	`"4.0"`

Response 200

{
  filename: string
  vcf: string
}

Errors

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

Contacts

On this page