Inboxes

Add an inbox

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

Registers a new inbox. It starts with no credential. The person connects it on the website.

A new inbox has needsReconnect: true and a reconnectUrl. Send the person to that link to sign in. The API never charges: when a paid slot is needed, it returns 402 with approveUrl for the person.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer followed by your API key.
`Content-Type`	string	Required	application/json

Request body

Name	Type	Required	Description
`label`	string	Required	Display name, like "Work Gmail".
`email`	string	Required	The mailbox address.
`provider`	string	Optional	google, microsoft, icloud, or imap. Detected from the address when left out. Custom domains default to imap.
`imapUser`	string	Optional	For provider icloud with your own domain on iCloud+: your iCloud Mail address (ending in icloud.com, me.com or mac.com), which is what signs in.

Response

201 Created. Returns inbox object.

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

Status	Error	Meaning
400	`invalid_request`	label or email is missing or invalid, or provider is not one of the four listed.
402	`upgrade_required or approval_required`	The plan needs an upgrade or a paid slot. approveUrl, when present, is a link for the person.
403	`email_not_verified`	The person has not confirmed their email address.
403	`inbox_limit`	The plan is at its inbox limit.

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 -X POST "https://getinboxtriage.com/api/inboxes" \
  -H "Authorization: Bearer $INBOX_TRIAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Work","email":"me@example.com","provider":"google"}'

const res = await fetch("https://getinboxtriage.com/api/inboxes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_TRIAGE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "label": "Work",
    "email": "me@example.com",
    "provider": "google"
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://getinboxtriage.com/api/inboxes",
    headers={"Authorization": f"Bearer {os.environ['INBOX_TRIAGE_KEY']}"},
    json={
        "label": "Work",
        "email": "me@example.com",
        "provider": "google",
    },
)
print(res.json())

Response201

{
  "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": null,
  "lastError": null,
  "status": "pending_credentials",
  "pausedAt": null,
  "connectionStatus": "blocked_on_secret",
  "needsReconnect": true,
  "sayToHuman": "This inbox needs to be reconnected before it can sync; open the Connect link.",
  "reconnectUrl": "https://getinboxtriage.com/connect/inbox_lx2k9a1b"
}