Skip to content

List connected mailboxes

GET
/v1/connections
curl --request GET \
  --url 'https://api.inboxcnx.com/v1/connections?status=initiated&provider=gmail&include=total' \
  --header 'Authorization: Bearer <token>'

Lists the connected mailboxes with the caller’s grants on each, newest first, so you can see which mailbox is healthy and which end user has to reconnect. Keyset pagination.

Requires the read:messages scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
status
string
Allowed values: initiated active error deleted
provider
string
Allowed values: gmail m365 imap
externalUserId
string
>= 1 characters <= 255 characters
cursor

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

string

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

limit

Page size, between 1 and 200. Default 50.

integer
>= 1 <= 200

Page size, between 1 and 200. Default 50.

include

total adds the number of matching results, counted up to 10000.

string
Allowed values: total

total adds the number of matching results, counted up to 10000.

Responses

Section titled “Responses”

200

Section titled “200”

A page of connections, each with the caller’s grants nested

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string
provider
required
string
Allowed values: gmail m365 imap
accountEmail
required
string
syncStatus
required
string
Allowed values: initiated active error deleted
health
required

ok, or what is wrong: error needs the mailbox owner (reauth_required: connect it again through POST /v1/connections/initiate; mailbox_unavailable: the mail provider refuses access, e.g. mail is disabled for the account), down and degraded are ours to fix. since is when the state began, where known. Null for a deleted connection, and for one whose grants are all revoked: it is no longer read for this application.

object
state
required
string
Allowed values: ok degraded down error
reason
required
string | null
Allowed values: reauth_required mailbox_unavailable subscription_expiring subscription_expired
since
required
string | null
missingAccess
required

What this application asks of a mailbox beyond reading that the end user has not consented to: change_mail (flags, labels, moves), send_mail. The mailbox was connected before the access was requested, or the end user left it out at consent. Reading is unaffected. Connect it again through POST /v1/connections/initiate to ask for it. Empty when the consent is current, and for a connection this application no longer reads.

Array<string>
Allowed values: change_mail send_mail
lastSyncedAt
required
string | null
createdAt
required
string
grants
required
Array<object>
object
id
required
string
status
required
string
Allowed values: pending active revoked
externalUserId
required
string | null
paused
required
boolean
blocked
required
boolean
subscribedRoles
required

The grant’s own folders, or null when it follows the application’s.

Array<string> | null
subscribedLabels
required
Array<string>
effectiveRoles
required

The folders that apply: subscribedRoles, else the application’s.

Array<string>
createdAt
required
string
nextCursor
required

Pass back as cursor for the next page. Null on the last page.

string | null
prevCursor
required

Pass back as cursor for the previous page. Null on the first page.

string | null
total

Present only when requested with include. exact is false once the count reaches 10000 (or the depth cap of a relevance search); count is then that cap.

object
count
required
integer
exact
required
boolean

Example 

{
  "data": [
    {
      "id": "5e8d2a10-3c4b-4f6e-9a7d-1b2c3d4e5f60",
      "provider": "gmail",
      "accountEmail": "owner@example.com",
      "syncStatus": "active",
      "health": {
        "state": "ok",
        "reason": null,
        "since": null
      },
      "missingAccess": [],
      "lastSyncedAt": "2026-10-23T07:58:12.000Z",
      "createdAt": "2026-10-01T06:00:00.000Z",
      "grants": [
        {
          "id": "9b2f0c4e-6a1d-4f3b-8c55-0d7e2a91b3c4",
          "status": "active",
          "externalUserId": "crm-user-42",
          "paused": false,
          "blocked": false,
          "subscribedRoles": null,
          "subscribedLabels": [],
          "effectiveRoles": [
            "inbox",
            "sent"
          ],
          "createdAt": "2026-10-01T06:00:00.000Z"
        }
      ]
    }
  ],
  "nextCursor": null,
  "prevCursor": null
}

400

Section titled “400”

Invalid query or malformed cursor

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

The credential lacks the read:messages scope

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}