Inboxes

Rename an inbox

PATCH https://getinboxtriage.com/api/inboxes/{id}

Renames an inbox. Only label can change.

Headers

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

Path parameters

Name	Type	Required	Description
`id`	string	Required	Inbox id from List inboxes, like inbox_lx2k9a1b.

Request body

Name	Type	Required	Description
`label`	string	Required	1 to 80 characters after trimming.

Response

200 OK. 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 is missing from the body.
400	`invalid_label`	label is empty or longer than 80 characters.
404	`inbox_not_found`	The inbox id is wrong or the inbox was removed.
409	`inbox_paused`	The person paused this inbox. They resume it on the Inboxes page.

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 PATCH "https://getinboxtriage.com/api/inboxes/inbox_lx2k9a1b" \
  -H "Authorization: Bearer $INBOX_TRIAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Personal"}'

const res = await fetch("https://getinboxtriage.com/api/inboxes/inbox_lx2k9a1b", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_TRIAGE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "label": "Personal"
  }),
});
const data = await res.json();

import os
import requests

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

Response200

{
  "id": "inbox_lx2k9a1b",
  "label": "Personal",
  "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
}