Inbox Triage
Start free trial

MCP tools

Triage actions

Change mail: trash, spam, archive, label, and star. Take the lease first.

Call these with tools/call on https://getinboxtriage.com/mcp. See the MCP overview for sign-in and the request format.

trash_message

Tool

Moves one message to Trash. Not a permanent delete.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageId string Required Message id from list_messages, search_mailbox, or show_inbox.
confirmed boolean Optional Only needed when the sender is on the VIP list: pass true after the human agrees in chat.
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "trash_message",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageId": "18f3a2b4c5d6e7f8"
    }
  }
}

mark_as_spam

Tool

Moves one message to Spam or Junk.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageId string Required Message id from list_messages, search_mailbox, or show_inbox.
confirmed boolean Optional Required when the sender is on the VIP list: pass true only after the human agrees in chat.
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mark_as_spam",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageId": "18f3a2b4c5d6e7f8"
    }
  }
}

archive_messages

Tool

Archives Gmail messages. Always needs confirmed: true after the person agrees. Up to 25 per call.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageIds string[] Required Message ids. Up to 25.
confirmed true Required Must be literal true. Confirms the human approved the archive in chat
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "archive_messages",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageIds": [
        "18f3a2b4c5d6e7f8"
      ],
      "confirmed": true
    }
  }
}

act_on_messages

Tool

Archives, trashes, marks as spam, stars, or labels messages on any inbox type, by row ids from show_inbox or by sender. VIP mail is skipped in bulk and needs the person's confirmation one at a time. Every change returns an undoId.

Inputs

NameTypeRequiredDescription
action enum Required What to do to the messages. One of: archive, trash, spam, star, unstar, label.
items object[] Optional Rows to act on, from show_inbox: inboxId and messageId.
sender object Optional Instead of items: every message from this sender still in the inbox
labelIds string[] Optional For action "label": Gmail label ids from list_labels
vipConfirmed boolean Optional true only after the person agreed in chat to act on this one VIP message
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "act_on_messages",
    "arguments": {
      "action": "archive",
      "items": [
        {
          "inboxId": "inbox_lx2k9a1b",
          "messageId": "18f3a2b4c5d6e7f8"
        }
      ]
    }
  }
}

apply_labels

Tool

Adds Gmail labels. More than one message needs confirmed: true. Up to 25 per call.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageIds string[] Required Explicit Gmail message ids only
labelIds string[] Required Explicit Gmail label ids (from list_labels)
confirmed true Optional Required true when messageIds.length > 1. Confirms the human approved the bulk label apply in chat
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "apply_labels",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageIds": [
        "18f3a2b4c5d6e7f8"
      ],
      "labelIds": [
        "Label_12"
      ]
    }
  }
}

remove_labels

Tool

Removes Gmail labels. Same limits as apply_labels.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageIds string[] Required Message ids. Up to 25.
labelIds string[] Required Gmail label ids from list_labels.
confirmed true Optional Required true when messageIds.length > 1
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "remove_labels",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageIds": [
        "18f3a2b4c5d6e7f8"
      ],
      "labelIds": [
        "Label_12"
      ]
    }
  }
}

star_messages

Tool

Stars or unstars Gmail messages. Same limits as apply_labels.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
messageIds string[] Required Message ids. Up to 25.
starred boolean Required true to star, false to unstar
confirmed true Optional Required true when messageIds.length > 1
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "star_messages",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "messageIds": [
        "18f3a2b4c5d6e7f8"
      ],
      "starred": true
    }
  }
}

begin_triage

Tool

Takes the per-inbox lease before a pass that changes mail.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
agentLabel string Required Short human-readable label identifying this agent/session, e.g. "claude-desktop" or "nightly-cron". Required.
force boolean Optional true to skip the cadence soft-check. Pass it only after the human explicitly asks to triage now.
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "begin_triage",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "agentLabel": "nightly-cleanup"
    }
  }
}

heartbeat_triage

Tool

Extends the lease. Call it about every 2 minutes.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
agentLabel string Required The same stable name you began the pass with.
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "heartbeat_triage",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "agentLabel": "nightly-cleanup"
    }
  }
}

end_triage

Tool

Releases the lease and records a summary.

Inputs

NameTypeRequiredDescription
inboxId string Required Inbox id from list_inboxes.
agentLabel string Required The same stable name you began the pass with.
summary string Optional Short human-readable summary of what this pass did, e.g. "archived 12 promos, left 2 VIP emails for review".
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "end_triage",
    "arguments": {
      "inboxId": "inbox_lx2k9a1b",
      "agentLabel": "nightly-cleanup"
    }
  }
}

get_triage_activity

Tool

Last pass and current lease for one inbox or all.

Inputs

NameTypeRequiredDescription
inboxId string Optional Inbox id from list_inboxes.
Example call 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_triage_activity",
    "arguments": {}
  }
}