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
`label`	`string`	No	1–100 characters; trimmed
`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

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

The mailbox's contacts at a glance: how many, their labels with counts, and birthdays in the next days days from today (the reader's date).

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	Default	Notes
`today`	`string`	No		matches `^\d{4}-\d{2}-\d{2}$`
`days`	`integer`	No	`30`	0–366; coerced from a string

Response 200

{
  total: number
  labels: {
    name: string
    count: number
  }[]
  birthdays: {
    contact: {
      contactId: string
      addressBookId: string
      version: number
      displayName: string
      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[]
      hasPhoto: boolean
      updatedAt: number
    }
    date: string
    days: number
    turns?: number
  }[]
}

Errors

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

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

Contacts that look like the same person (a shared email, phone number or full name), fullest first in each group.

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

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

Response 200

{
  groups: {
    key: string
    reason: "email" | "name" | "phone"
    value: string
    contacts: {
      contactId: string
      addressBookId: string
      version: number
      displayName: string
      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[]
      hasPhoto: boolean
      updatedAt: number
    }[]
  }[]
}

Errors

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

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

The people the mailbox writes to most (its recent sent mail), with their contacts. Needs mail:read as well.

Auth: user access token or platform agent key · Scopes: contacts:read, mail:read

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

Query parameter	Type	Required	Default	Notes
`limit`	`integer`	No	`12`	1–50; coerced from a string

Response 200

{
  frequent: {
    address: string
    name?: string
    count: number
    lastAt: number
    contact?: {
      contactId: string
      addressBookId: string
      version: number
      displayName: string
      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[]
      hasPhoto: boolean
      updatedAt: number
    }
  }[]
}

Errors

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

`POST /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/merge`

Merges contacts into one (keep): blank fields filled, every distinct email, phone, address and label kept; the others are deleted.

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
`keep`	`object`	Yes
`keep.addressBookId`	`string`	Yes	1–40 characters
`keep.contactId`	`string`	Yes	1–40 characters
`merge`	`object[]`	Yes	1–9 items
`merge[].addressBookId`	`string`	Yes	1–40 characters
`merge[].contactId`	`string`	Yes	1–40 characters

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/contacts/bulk`

One change to many contacts: add or remove labels, move to another address book, or delete.

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
`contacts`	`object[]`	Yes	1–500 items
`contacts[].addressBookId`	`string`	Yes	1–40 characters
`contacts[].contactId`	`string`	Yes	1–40 characters
`addLabels`	`any JSON[]`	No	up to 10 items
`removeLabels`	`any JSON[]`	No	up to 10 items
`moveTo`	`string`	No	up to 40 characters
`delete`	`true`	No

Response 200

{
  changed: number
}

Errors

Status	Message
`400`	Choose one change: labels, a move or delete.
`403`	Mailboxes are only available to members.
`404`	Mailbox not found

`PATCH /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/labels/:label`

Renames a label on every contact that has it.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:label`	Hosted runner type label, e.g. `linux-arm64`.

Request body

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

Response 200

{
  changed: number
}

Errors

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

`DELETE /v1/orgs/:orgId/mail/mailboxes/:mailboxId/contacts/labels/:label`

Removes a label from every contact (the contacts stay).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:mailboxId`	Mailbox id (`mbx_…`).
`:label`	Hosted runner type label, e.g. `linux-arm64`.

Response 200

{
  changed: number
}

Errors

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

`GET /v1/orgs/:orgId/mail/contacts/lookup`

Contacts with an email address across the person's mailboxes in the org (or one, mailboxId): Mail's sender cards and Customers' "In Contacts". Mailboxes they aren't a member of are never read.

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

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

Query parameter	Type	Required	Notes
`email`	`string`	Yes	up to 320 characters; trimmed; email address
`mailboxId`	`string`	No	up to 40 characters

Response 200

{
  matches: {
    mailboxId: string
    mailboxAddress: string
    contact: {
      contactId: string
      addressBookId: string
      version: number
      displayName: string
      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[]
      hasPhoto: boolean
      updatedAt: number
    }
  }[]
}

Errors

Status	Message
`403`	Mailboxes are only available to members.

`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