Mailboxes

A mailbox is an email account, on Google or Microsoft, that a user has connected to Carom. Carom imports its mail into threads, its correspondents into contacts, and its calendars into calendar events. Use this resource to see which mailboxes are connected, whether they are healthy, and how far their imports have got.

Each mailbox has one owner. Its view policy and send policy decide who else can read its mail and send from it: nobody, everyone in the account, or selected users and groups named in its grants. Your key sees the mailboxes your key’s user can view. Connecting a mailbox, changing its policies, and granting access happen in the Carom app.

#The mailbox object

Returned by every mailbox endpoint. List mailboxes adds two fields about your key’s user’s sending rights; retrieving a single mailbox adds its reconnect URL and import history.

A mailbox is working when connection_status is connected and sync_state is neither attention_needed nor deactivated. Otherwise, missing_required_capabilities lists any permissions the owner didn’t grant, and configuration.error_detail describes the last connection error: its category says whether the owner must reconnect, and retriable says whether the error is temporary.

Attributes

idstring · uuid

Unique identifier for the mailbox.
namestring · nullable

Display name for the mailbox.
email_addressstring · nullable
user_idstring · uuid · nullable

The user who owns the mailbox.
primaryboolean · nullable

True for the mailbox the owner signed up to Carom with.
connection_statusstring

The state of Carom’s connection to the provider. incomplete means the owner connected without granting every required permission; error means the provider rejected Carom, and configuration.error_detail says why. The owner fixes either by reconnecting in the Carom app.

connectedincompleteerrordisconnected
authorizedboolean · nullable

Whether Carom holds working credentials for the mailbox.
capabilitiesobject

Which permissions the owner granted at the provider, each true or false.
Show 5 child attributesHide child attributes
- mail_readboolean
  Read mail. Required.
- mail_sendboolean
  Send mail as the mailbox.
- mail_modifyboolean
  Change read state and flags at the provider. Needed for label_sync.
- calendar_readboolean
- contacts_readboolean
  Read the provider’s address book. Needed for contacts_sync.
missing_required_capabilitiesarray of strings

Required permissions the owner hasn’t granted: identity (permission to confirm the account’s email address, requested at every sign-in), mail_read, or both. Empty when the connection is complete.
sync_statestring · nullable

Null until the first import starts. importing means Carom has started importing the mailbox and adds new mail as it arrives. deactivated means the owner’s account was deactivated and the mailbox disconnected. attention_needed means Carom may not be receiving new mail for this mailbox; the owner should reconnect it in the Carom app.

importingdeactivatedattention_needed
configurationobject · nullable

Provider details and the last connection error.
Show 3 child attributesHide child attributes
- providerstring · nullable
  googlemicrosoft
- granted_scopesarray of strings · nullable
  The OAuth scopes the provider granted, as the provider names them.
- error_detailobject · nullable
  
  The error from the last connection attempt. Null when the mailbox is healthy.
  Show 4 child attributesHide child attributes
  - codestring
  - messagestring
  - categorystring
    auth errors, such as a revoked token, need the owner to reconnect.
    authscopepermissionproviderrate_limitunknown
  - retriableboolean
    True for temporary provider errors and rate limits.
view_policystring

Who besides the owner can read the mailbox’s mail: nobody, everyone in the account, or the users and groups in its grants.

noneeveryoneselected
send_policystring

Who besides the owner can send from the mailbox, with the same three values.

noneeveryoneselected
contact_policystring

Which correspondents from this mailbox can become contacts the whole team sees. all admits every address; business admits addresses at non-personal domains; existing_orgs admits only people at an organization the account already has; with none, contacts from this mailbox stay private to the owner. Addresses at your own company’s domain never count.

allbusinessexisting_orgsnone
interaction_sharingstring

How much of the owner’s correspondence with those team-visible contacts teammates can see: only the contact, or also the fact that the owner knows them. Reading the mailbox’s mail is controlled by view_policy.

noneknowledge
label_syncboolean

Whether read state and flags the owner sets in Carom are copied to the provider. Takes effect only when capabilities.mail_modify is true.
contacts_syncboolean

Whether Carom imports the provider’s address book. Takes effect only when capabilities.contacts_read is true.
contacts_synced_atstring · date-time · nullable
user_sendableboolean

Only on List mailboxes. Whether your key’s user can send from this mailbox now: it is connected with send permission, and that user owns it or is allowed by its send policy.
user_sendability_reasonstring · nullable

Only on List mailboxes. Why user_sendable is false; null when it is true.

connection_not_authorizeduser_permission_deniedcapability_not_granted
subscription_count, thread_count, contact_count, calendar_event_count, file_countinteger · nullable

How many users follow this mailbox through a mailbox subscription, and how many threads, contacts, calendar events, and files came from it. Computed by Retrieve a mailbox, and by List mailboxes when you pass expanded=true. Null otherwise.

The mailbox object

{
  "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
  "name": "Dana Whitfield",
  "email_address": "dana@harborline.example",
  "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
  "primary": true,
  "connection_status": "connected",
  "authorized": true,
  "capabilities": {
    "mail_read": true,
    "mail_send": true,
    "mail_modify": true,
    "calendar_read": true,
    "contacts_read": false
  },
  "missing_required_capabilities": [],
  "sync_state": "importing",
  "configuration": {
    "provider": "google",
    "granted_scopes": [
      "openid",
      "https://www.googleapis.com/auth/gmail.modify",
      …
    ],
    "error_detail": null
  },
  "view_policy": "selected",
  "send_policy": "none",
  "contact_policy": "business",
  "interaction_sharing": "knowledge",
  "label_sync": true,
  "contacts_sync": false,
  "contacts_synced_at": null,
  "user_sendable": true,
  "user_sendability_reason": null,
  "subscription_count": 2,
  "thread_count": 18422,
  "contact_count": 1307,
  "calendar_event_count": 2140,
  "file_count": 3916
}

get/mailboxes Read key

#List mailboxes

Returns every mailbox visible to your key: the ones your key’s user owns, the ones open to everyone in the account, and the ones that user has been granted. Returns every mailbox in one response; the list isn’t paginated.

Query parameters

expandedboolean

Compute thread_count, contact_count, calendar_event_count, file_count, and subscription_count for each mailbox. Makes the request slower.

Returns

collectionobject

Every mailbox visible to your key.
Show 2 child attributesHide child attributes
- recordsarray of mailboxes
  
  Each with user_sendable and user_sendability_reason for your key’s user.
- total_resultsinteger
  
  The number of mailboxes in records.

Errors

400invalid_requestexpanded isn’t a boolean.

get/mailboxes

curl "https://api.carom.io/mailboxes?expanded=true" \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "collection": {
    "records": [
      {
        "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
        "email_address": "dana@harborline.example",
        "connection_status": "connected",
        "user_sendable": true,
        "user_sendability_reason": null,
        "thread_count": 18422,
        …
      },
      {
        "id": "6f1a9c3e-8b2d-4a7f-9e5c-1d3b7a9f2c86",
        "email_address": "sales@harborline.example",
        "connection_status": "connected",
        "view_policy": "everyone",
        "send_policy": "selected",
        "user_sendable": false,
        "user_sendability_reason": "user_permission_denied",
        "thread_count": 6051,
        …
      }
    ],
    "total_results": 2
  }
}

get/mailboxes/{id} Read key

#Retrieve a mailbox

Returns a single mailbox with its counts and its mail and calendar imports, newest first. Use it to follow an import started with Start an import.

Path parameters

idstring · uuidrequired

The mailbox’s id.

Returns

The mailbox object, wrapped in mailbox, with these additional attributes.

connect_urlstring · nullable

The provider sign-in URL the Carom app uses to reconnect the mailbox, created fresh on each request. Null when the mailbox’s provider has no sign-in to reconnect through.
importsarray of objects · nullable

Every mail import for this mailbox, newest first.
Show 10 child attributesHide child attributes
- idstring · uuid
- statusstring · nullable
  processingcompletefailed
- resultstring · nullable
  The outcome in one field. Matches status until the import completes, then says whether every thread was imported, some failed, all failed, or there was nothing to import.
  processingimportedpartialfailednothing_to_import
- total_thread_countinteger · nullable
- imported_thread_countinteger · nullable
- skipped_thread_countinteger · nullable
- failed_thread_countinteger · nullable
- started_at, last_progress_at, completed_atstring · date-time · nullable
- errorobject · nullable
  
  Why a failed import stopped, with a code, message, category, and retriable, which is true when starting another import may succeed. category is one of these:
  
  timeoutproviderrate_limitauthparseunknown
calendar_importsarray of objects · nullable

Every import of one of this mailbox’s calendars, newest first.
Show 9 child attributesHide child attributes
- idstring · uuid
- calendar_idstring · uuid
- statusstring · nullable
  partial means the import stopped before every event was imported.
  processingcompletepartialfailed
- total_event_countinteger · nullable
- imported_event_countinteger · nullable
- skipped_event_countinteger · nullable
- failed_event_countinteger · nullable
- started_atstring · date-time · nullable
- completed_atstring · date-time · nullable

Errors

404record_not_foundNo mailbox with that id is visible to your key.

get/mailboxes/{id}

curl https://api.carom.io/mailboxes/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "mailbox": {
    "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
    "email_address": "dana@harborline.example",
    "connection_status": "connected",
    …
    "connect_url": "https://accounts.google.com/o/oauth2/v2/auth?…",
    "imports": [
      {
        "id": "f3b8d1a6-9e2c-4d7f-a4b1-6c0e5d9f2a73",
        "status": "complete",
        "result": "partial",
        "total_thread_count": 18440,
        "imported_thread_count": 18422,
        "skipped_thread_count": 15,
        "failed_thread_count": 3,
        "started_at": "2026-09-02T08:14:05.566Z",
        "last_progress_at": "2026-09-02T09:47:31.317Z",
        "completed_at": "2026-09-02T09:47:33.090Z",
        "error": null
      }
    ],
    "calendar_imports": [
      {
        "id": "1e5a9d3c-7b2f-4a8e-b6d4-3c9f1a7e5b28",
        "calendar_id": "7b3d9f1e-5c8a-4e2b-9d6f-0a4c8e2b6d91",
        "status": "complete",
        "imported_event_count": 2140,
        …
      }
    ]
  }
}

post/mailboxes/{mailbox_id}/imports Write key

#Start an import

Queues a full import of the mailbox: Carom reads its mail from the provider again, imports each of its calendars that syncs, and, when contacts_sync is on, refreshes its address book. New mail arrives on its own once a mailbox is connected, so you need this only to catch up after a problem or to pick up address-book changes sooner. Only the mailbox’s owner can start an import.

The import runs in the background. Follow it in imports on Retrieve a mailbox.

Path parameters

mailbox_idstring · uuidrequired

Returns

The ok object, {"ok": "ok"}, once the import is queued.

Errors

403permission_deniedYour key’s user can see the mailbox but doesn’t own it.
404record_not_foundNo mailbox with that id is visible to your key.
422mailbox_not_connectedThe mailbox has no working connection with permission to read mail. The owner must reconnect it in the Carom app.
422outbound_disabledYour account’s subscription doesn’t currently allow imports.

post/mailboxes/{mailbox_id}/imports

curl -X POST https://api.carom.io/mailboxes/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/imports \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{ "ok": "ok" }

get/mailboxes/{mailbox_id}/grants Read key

#List mailbox grants

Returns the users and groups that have been given access to a mailbox. A grant matters when the mailbox’s view_policy or send_policy is selected. Only the mailbox’s owner can list its grants.

Path parameters

mailbox_idstring · uuidrequired

Returns

mailbox_grantsarray of objects
Show 7 child attributesHide child attributes
- idstring · uuid
- mailbox_idstring · uuid
- user_idstring · uuid · nullable
  The user granted access. Exactly one of user_id and group_id is set.
- group_idstring · uuid · nullable
  The group granted access. Every member of the group has it.
- levelstring
  view lets the grantee read the mailbox’s mail. send also lets them send from it.
  viewsend
- granted_by_user_idstring · uuid · nullable
- created_atstring · date-time

Errors

403permission_deniedYour key’s user can see the mailbox but doesn’t own it.
404record_not_foundNo mailbox with that id is visible to your key.

get/mailboxes/{mailbox_id}/grants

curl https://api.carom.io/mailboxes/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/grants \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "mailbox_grants": [
    {
      "id": "4d9b1e7c-3a6f-4e2d-8c5b-1f7a9d3e6b82",
      "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "user_id": "3b7e1f9a-2c5d-4e8b-a6f0-8d2c4b9e1a75",
      "group_id": null,
      "level": "send",
      "granted_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
      "created_at": "2026-09-03T17:22:48.880Z"
    },
    {
      "id": "a2c6e8f0-5b1d-4a7e-9c3f-8d4b2e6a0c57",
      "mailbox_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "user_id": null,
      "group_id": "5c8a2e4f-1b7d-4c9e-b3a6-0f9d2e8c7b14",
      "level": "view",
      "granted_by_user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
      "created_at": "2026-09-03T17:23:10.286Z"
    }
  ]
}