API reference

Contacts

Address books, contacts, photos and vCard import and export for the mailboxes you belong to.

Read the Guide

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  addressBooks: {
    addressBookId: string
    name: string
    isDefault: boolean
    version: number
  }[]
}

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

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

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

nameany JSONrequired

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {}
  }'

Send it from this page with your session or a key.

Response 201

{
  addressBook: {
    addressBookId: string
    name: string
    isDefault: boolean
    version: number
  }
}

PATCH/v1/orgs/:orgId/mail/mailboxes/:mailboxId/address-books/:addressBookId

Renames an address book.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).

Request body

nameany JSONrequired

Errors

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

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {}
  }'

Send it from this page with your session or a key.

Response 200

{
  addressBook: {
    addressBookId: string
    name: string
    isDefault: boolean
    version: number
  }
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).

Errors

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

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Query parameters

qstring
Up to 200 characters.
addressBookIdstring
Up to 40 characters.
labelstring
1–100 characters. Trimmed.
cursorstring
Up to 2,000 characters.
limitinteger
1–500. Coerced from a string.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Query parameters

todaystring
Matches ^\d{4}-\d{2}-\d{2}$.
daysinteger
Default 30. 0–366. Coerced from a string.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/summary' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
  }[]
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/duplicates' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
    }[]
  }[]
}

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: A person's token or an API key, as Authorization: Bearer.
Scopes: contacts:read, mail:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Query parameters

limitinteger
Default 12. 1–50. Coerced from a string.

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/frequent' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
    }
  }[]
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

keepobjectrequired
keep.addressBookIdstringrequired
1–40 characters.
keep.contactIdstringrequired
1–40 characters.
mergeobject[]required
1–9 items.
merge[].addressBookIdstringrequired
1–40 characters.
merge[].contactIdstringrequired
1–40 characters.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/merge' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "keep": {
      "addressBookId": "<addressBookId>",
      "contactId": "<contactId>"
    },
    "merge": [
      {
        "addressBookId": "<addressBookId>",
        "contactId": "<contactId>"
      }
    ]
  }'

Send it from this page with your session or a key.

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
  }
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).

Request body

contactsobject[]required
1–500 items.
contacts[].addressBookIdstringrequired
1–40 characters.
contacts[].contactIdstringrequired
1–40 characters.
addLabelsany JSON[]
Up to 10 items.
removeLabelsany JSON[]
Up to 10 items.
moveTostring
Up to 40 characters.
deletetrue

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/bulk' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      {
        "addressBookId": "<addressBookId>",
        "contactId": "<contactId>"
      }
    ]
  }'

Send it from this page with your session or a key.

Response 200

{
  changed: number
}

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

Renames a label on every contact that has it.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

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

Request body

nameany JSONrequired

Errors

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

curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/labels/{label}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": {}
  }'

Send it from this page with your session or a key.

Response 200

{
  changed: number
}

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

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

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

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

Errors

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

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/contacts/labels/{label}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  changed: number
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).

Query parameters

emailstringrequired
Up to 320 characters. Trimmed. Email address.
mailboxIdstring
Up to 40 characters.

Errors

403Mailboxes are only available to members.

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/contacts/lookup?email=person%40example.com' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
    }
  }[]
}

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

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

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).

Request body

fullNameany JSON
nameobject
name.familyany JSON
Default "".
name.givenany JSON
Default "".
name.additionalany JSON
Default "".
name.prefixany JSON
Default "".
name.suffixany JSON
Default "".
nicknameany JSON
emailsany JSON
phonesany JSON
addressesobject[]
Up to 10 items.
addresses[].type"home" | "work" | "other"
Default "home".
addresses[].poBoxany JSON
Default "".
addresses[].extendedany JSON
Default "".
addresses[].streetany JSON
Default "".
addresses[].localityany JSON
Default "".
addresses[].regionany JSON
Default "".
addresses[].postalCodeany JSON
Default "".
addresses[].countryany JSON
Default "".
urlsany JSON
organizationany JSON
departmentany JSON
titleany JSON
birthdaystring
Matches ^(\d{4}|-)-\d{2}-\d{2}$|^$.
anniversarystring
Matches ^(\d{4}|-)-\d{2}-\d{2}$|^$.
notesstring
Up to 32,000 characters.
categoriesany JSON[]
Up to 30 items.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName": {},
    "name": {
      "family": "",
      "given": "",
      "additional": ""
    },
    "nickname": {}
  }'

Send it from this page with your session or a key.

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
  }
}

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

A contact.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
  }
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Request body

fullNameany JSON
nameobject
name.familyany JSON
Default "".
name.givenany JSON
Default "".
name.additionalany JSON
Default "".
name.prefixany JSON
Default "".
name.suffixany JSON
Default "".
nicknameany JSON
emailsany JSON
phonesany JSON
addressesobject[]
Up to 10 items.
addresses[].type"home" | "work" | "other"
Default "home".
addresses[].poBoxany JSON
Default "".
addresses[].extendedany JSON
Default "".
addresses[].streetany JSON
Default "".
addresses[].localityany JSON
Default "".
addresses[].regionany JSON
Default "".
addresses[].postalCodeany JSON
Default "".
addresses[].countryany JSON
Default "".
urlsany JSON
organizationany JSON
departmentany JSON
titleany JSON
birthdaystring
Matches ^(\d{4}|-)-\d{2}-\d{2}$|^$.
anniversarystring
Matches ^(\d{4}|-)-\d{2}-\d{2}$|^$.
notesstring
Up to 32,000 characters.
categoriesany JSON[]
Up to 30 items.
ifVersioninteger
≥ 0.

Errors

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

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fullName": {},
    "name": {
      "family": "",
      "given": "",
      "additional": ""
    },
    "nickname": {}
  }'

Send it from this page with your session or a key.

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
  }
}

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

Deletes a contact and its photo.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Errors

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

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

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

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

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}/photo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  url: string
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Request body (up to 2,048 KB)

contentType"image/jpeg" | "image/png" | "image/gif" | "image/webp"required
datastringrequired
At least 1 character.

Errors

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

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}/photo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "contentType": "image/jpeg",
    "data": "example"
  }'

Send it from this page with your session or a key.

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
  }
}

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

Removes the contact's photo.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).
contactId
Contact id (ctc_…).

Errors

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

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/contacts/{contactId}/photo' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

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
  }
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:write

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).

Request body (up to 6,144 KB)

vcfstringrequired
1–5,242,880 characters.

Errors

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

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/import' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "vcf": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  created: number
  updated: number
  skipped: number
}

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: A person's token or an API key, as Authorization: Bearer.
Scope: contacts:read

Get an API key

Path parameters

orgId
Organization id (org_…).
mailboxId
Mailbox id (mbx_…).
addressBookId
Address book id (abk_…).

Query parameters

version"3.0" | "4.0"
Default "4.0".

Errors

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

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/mail/mailboxes/{mailboxId}/address-books/{addressBookId}/export' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  filename: string
  vcf: string
}