Triage

Begin a triage pass

POST https://getinboxtriage.com/api/inboxes/{id}/triage/begin

Takes a 8 minute lease before a pass that archives, labels, marks spam, or writes a batch of drafts. Reading never needs one.

When the last pass was too recent you get 200 with ok: false, reason: "cadence", and nextEligibleAt. Wait, or pass force only when the person asks.

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
`agentLabel`	string	Required	A stable name for your agent, up to 80 characters.
`force`	boolean	Optional	true skips the cadence check. Use it only when the person asks.

Response

200 OK.

Name	Type	Description
`ok`	boolean	true when you hold the lease.
`leaseExpiresAt`	string	When the lease runs out. Send a heartbeat before then.
`startedAt`	string	When the pass began.
`agentLabel`	string	Your label.
`reason`	string	cadence when ok is false because the last pass was too recent.
`nextEligibleAt`	string	With reason cadence: when a new pass is allowed.

Errors

Status	Error	Meaning
400	`invalid_request`	agentLabel is missing.
404	`inbox_not_found`	The inbox id is wrong or the inbox was removed.
409	`lease_busy`	Another agent holds the lease. The body also has ok: false, busy: true, heldBy, and leaseExpiresAt.
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 POST "https://getinboxtriage.com/api/inboxes/inbox_lx2k9a1b/triage/begin" \
  -H "Authorization: Bearer $INBOX_TRIAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentLabel":"nightly-cleanup"}'

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

import os
import requests

res = requests.post(
    "https://getinboxtriage.com/api/inboxes/inbox_lx2k9a1b/triage/begin",
    headers={"Authorization": f"Bearer {os.environ['INBOX_TRIAGE_KEY']}"},
    json={
        "agentLabel": "nightly-cleanup",
    },
)
print(res.json())

Response200

{
  "ok": true,
  "leaseExpiresAt": "2026-09-18T09:10:00.000Z",
  "startedAt": "2026-09-18T09:00:00.000Z",
  "agentLabel": "nightly-cleanup"
}