Inboxes

List inboxes

GET https://getinboxtriage.com/api/inboxes

Lists connected inboxes with their live connection status. Paused inboxes are left out.

Trust connectionStatus and needsReconnect, not status. When needsReconnect is true, give reconnectUrl to the person.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer followed by your API key.

Response

200 OK. Returns array of inbox objects.

Name	Type	Description
`id`	string	Inbox id.
`label`	string	Display name, like "Work".
`provider`	string	google, microsoft, icloud, or imap.
`email`	string	The mailbox address.
`imapHost`	string \| null	The IMAP server, for icloud/imap inboxes only.
`imapPort`	number \| null	The IMAP port (993 or 143), for icloud/imap inboxes only.
`imapUser`	string \| null	The IMAP login username, when it differs from email.
`folders`	string[]	Folders that sync. Defaults to Inbox, Sent, and Drafts.
`status`	string	Last recorded state: pending_credentials, connected, demo, or error. Can lag. Trust connectionStatus and needsReconnect instead.
`connectionStatus`	string	credentials_present when a credential is stored, or blocked_on_secret when the person still has to connect.
`needsConnect`	boolean	true when this inbox has never had a real credential stored; open the Connect link to sign in.
`needsReconnect`	boolean	true when the person has to connect or reconnect the inbox before it can sync.
`sayToHuman`	string	Only when needsConnect or needsReconnect is true. A sentence to show the person.
`reconnectUrl`	string	Only when needsConnect or needsReconnect is true. Give this link to the person.
`lastSyncedAt`	string \| null	ISO time of the last finished sync.
`lastError`	string \| null	The last sync error, if any.
`createdAt`	string	ISO time the inbox was added.
`connectedAt`	string \| null	ISO time this inbox first got a real (non-demo) credential. Stays set even if the credential is later lost.
`pausedAt`	string \| null	ISO time the inbox was paused, or null. A paused inbox keeps its mail but stops syncing and is hidden from agents.

Errors

Any route can also return 401 for a bad key, 402 when the trial ended or payment failed, and 429 when you send too many requests. See Errors.

Request

curl "https://getinboxtriage.com/api/inboxes" \
  -H "Authorization: Bearer $INBOX_TRIAGE_KEY"

const res = await fetch("https://getinboxtriage.com/api/inboxes", {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_TRIAGE_KEY}`,
  },
});
const data = await res.json();

import os
import requests

res = requests.get(
    "https://getinboxtriage.com/api/inboxes",
    headers={"Authorization": f"Bearer {os.environ['INBOX_TRIAGE_KEY']}"},
)
print(res.json())

Response200

[
  {
    "id": "inbox_lx2k9a1b",
    "label": "Work",
    "provider": "google",
    "email": "me@example.com",
    "imapHost": null,
    "imapPort": null,
    "imapUser": null,
    "folders": [
      "INBOX",
      "SENT",
      "DRAFT"
    ],
    "createdAt": "2026-09-01T15:04:05.000Z",
    "lastSyncedAt": "2026-09-18T08:30:12.000Z",
    "lastError": null,
    "status": "connected",
    "pausedAt": null,
    "connectionStatus": "credentials_present",
    "needsReconnect": false
  }
]