Inbox
Inbox tools exposed over the SuperBooks MCP API.
The inbox domain exposes 3 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
inbox_delete
Scope tier: destructive · Destructive — requires the two-gate check
SOFT-DELETE an inbox item — sets status='deleted' and clears its transaction_id / attachment_id; the item itself is retained, not removed. DESTRUCTIVE because it irreversibly: (a) detaches the item from its linked transaction, deleting that attachment; (b) RESETS the linked transaction's tax_rate and tax_type to NULL if that was its only attachment; (c) discards any pending match suggestions for this inbox item. The uploaded file itself is retained. Returns deleted: false if the inbox item was not found for this team — does not throw. Confirm with the user before calling.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Inbox item id (UUID) to soft-delete. This action's side-effects on linked transactions are irreversible. |
inbox_list
Scope tier: read
List inbox items (uploaded receipts / forwarded invoices) for the current team, newest first. EXCLUDES soft-deleted items (status='deleted') and grouped follow-ups, so each primary item appears once. Filter by exact status and/or a free-text query q (matches display_name / file_name / description; numeric q also matches amount within +/- 10% tolerance). Cursor pagination: pass the cursor from the previous page to get the next one.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | processing | pending | archived | new | analyzing | suggested_match | no_match | done | deleted | other (nullable) | no | Filter by exact inbox_status. Common values: 'pending' (awaiting action), 'done' (matched), 'suggested_match' (auto-matched, needs confirm), 'no_match' (no candidate transaction). Omit to see everything except deleted. |
q | string (nullable) | no | Free-text query — substring-matches display_name / file_name / description, case-insensitively. If parseable as a number, ALSO matches inbox items with amount within +/- 10% of that value. |
cursor | string (nullable) | no | Pagination cursor from the previous page's cursor. Omit on the first page. |
pageSize | integer | no | Items per page (1-100). Defaults to 20. Default: 20. |
inbox_match
Scope tier: write
Link an inbox item (receipt / invoice) to a bank transaction. NOT a simple flag flip — this: (a) attaches each grouped sibling to the same transaction; (b) copies tax_amount / tax_rate+tax_type from the inbox item onto the transaction (only if the inbox has them); (c) sets each linked inbox item's status='done' and stores its attachment_id + transaction_id. IDEMPOTENT when the item is already matched to the SAME transaction. Throws if the item is already matched to a DIFFERENT transaction, if any grouped sibling is matched to a different txn, or if the target transaction does not exist for this team.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Inbox item id (UUID). If this is a grouped follow-up, the entire group is matched together. |
transactionId | string (uuid) | yes | Target transaction id (UUID). Must belong to the same team or the operation throws. |