mailbox

request_inbound_action

Idempotent

Propose a scan, forward or discard through POST /v1/inbound-items/:id/actions. Agent keys only; the proposal always waits for the owner's approval (awaiting_member_approval: true) and never charges credits or moves mail by itself. Send the item's current version as action.expected_version, a stable idempotency_key for retries, and for forward a complete US destination (first_class requires untracked_acknowledged: true). Forward destinations and discard proposals are checked against the agent's inbound_policy server-side. One open action per item. Required scope: inbound.act (legacy aliases accepted). Member keys read their own live items; agent keys read items bound or assigned to them, in their key's environment. Proposals are agent-only and always wait for the owner: they never charge credits, buy postage, open, forward or discard anything by themselves. Forward destinations and discard proposals are checked against the agent's structured inbound policy. Image URLs are never issued to agents. Stop on denial; never switch keys or mail APIs to bypass it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`action`	Yes
`item_id`	Yes
`idempotency_key`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 22, 2026

changedInput schema / properties / action / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "expected_quote": {
-        "additionalProperties": false,
-        "properties": {
-          "billable": {
-            "type": "boolean"
-          },
-          "cost_cents": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "cost_cents",
-          "billable"
-        ],
-        "type": "object"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "scan",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "destination": {
-        "additionalProperties": false,
-        "properties": {
-          "city": {
-            "maxLength": 80,
-            "minLength": 1,
-            "type": "string"
-          },
-          "company": {
-            "anyOf": [
-              {
-                "maxLength": 100,
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null
-          },
-          "country": {
-            "const": "US",
-            "default": "US",
-            "type": "string"
-          },
-          "line1": {
-            "maxLength": 120,
-            "minLength": 1,
-            "type": "string"
-          },
-          "line2": {
-            "anyOf": [
-              {
-                "maxLength": 120,
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null
-          },
-          "name": {
-            "maxLength": 100,
-            "minLength": 1,
-            "type": "string"
-          },
-          "postal_code": {
-            "pattern": "^\\d{5}(-\\d{4})?$",
-            "type": "string"
-          },
-          "state": {
-            "pattern": "^[A-Z]{2}$",
-            "type": "string"
-          }
-        },
-        "required": [
-          "name",
-          "line1",
-          "city",
-          "state",
-          "postal_code"
-        ],
-        "type": "object"
-      },
-      "expected_quote": {
-        "additionalProperties": false,
-        "properties": {
-          "billable": {
-            "type": "boolean"
-          },
-          "cost_cents": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "cost_cents",
-          "billable"
-        ],
-        "type": "object"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "mail_class": {
-        "default": "priority",
-        "enum": [
-          "first_class",
-          "priority",
-          "certified",
-          "certified_return_receipt",
-          "fedex_ground",
-          "fedex_express",
-          "fedex_2day",
-          "fedex_overnight"
-        ],
-        "type": "string"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "forward",
-        "type": "string"
-      },
-      "untracked_acknowledged": {
-        "default": false,
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version",
-      "destination"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "confirmed": {
-        "const": true,
-        "type": "boolean"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "discard",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version",
-      "confirmed"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "expected_quote": {
+        "additionalProperties": false,
+        "properties": {
+          "billable": {
+            "type": "boolean"
+          },
+          "cost_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "max_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "cost_cents",
+          "billable"
+        ],
+        "type": "object"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "scan",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "destination": {
+        "additionalProperties": false,
+        "properties": {
+          "city": {
+            "maxLength": 80,
+            "minLength": 1,
+            "type": "string"
+          },
+          "company": {
+            "anyOf": [
+              {
+                "maxLength": 100,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null
+          },
+          "country": {
+            "const": "US",
+            "default": "US",
+            "type": "string"
+          },
+          "line1": {
+            "maxLength": 120,
+            "minLength": 1,
+            "type": "string"
+          },
+          "line2": {
+            "anyOf": [
+              {
+                "maxLength": 120,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null
+          },
+          "name": {
+            "maxLength": 100,
+            "minLength": 1,
+            "type": "string"
+          },
+          "postal_code": {
+            "pattern": "^\\d{5}(-\\d{4})?$",
+            "type": "string"
+          },
+          "state": {
+            "pattern": "^[A-Z]{2}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "line1",
+          "city",
+          "state",
+          "postal_code"
+        ],
+        "type": "object"
+      },
+      "expected_quote": {
+        "additionalProperties": false,
+        "properties": {
+          "billable": {
+            "type": "boolean"
+          },
+          "cost_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          },
+          "max_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "cost_cents",
+          "billable"
+        ],
+        "type": "object"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "mail_class": {
+        "default": "priority",
+        "enum": [
+          "first_class",
+          "priority",
+          "certified",
+          "certified_return_receipt",
+          "fedex_ground",
+          "fedex_express",
+          "fedex_2day",
+          "fedex_overnight"
+        ],
+        "type": "string"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "forward",
+        "type": "string"
+      },
+      "untracked_acknowledged": {
+        "default": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version",
+      "destination"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "confirmed": {
+        "const": true,
+        "type": "boolean"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "discard",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version",
+      "confirmed"
+    ],
+    "type": "object"
+  }
+]

Changed2 schema fields changedSep 21, 2026

changedInput schema / properties / action / oneOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "expected_quote": {
-        "additionalProperties": false,
-        "properties": {
-          "billable": {
-            "type": "boolean"
-          },
-          "cost_cents": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "cost_cents",
-          "billable"
-        ],
-        "type": "object"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "scan",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "destination": {
-        "additionalProperties": false,
-        "properties": {
-          "city": {
-            "maxLength": 80,
-            "minLength": 1,
-            "type": "string"
-          },
-          "company": {
-            "anyOf": [
-              {
-                "maxLength": 100,
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null
-          },
-          "country": {
-            "const": "US",
-            "default": "US",
-            "type": "string"
-          },
-          "line1": {
-            "maxLength": 120,
-            "minLength": 1,
-            "type": "string"
-          },
-          "line2": {
-            "anyOf": [
-              {
-                "maxLength": 120,
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "default": null
-          },
-          "name": {
-            "maxLength": 100,
-            "minLength": 1,
-            "type": "string"
-          },
-          "postal_code": {
-            "pattern": "^\\d{5}(-\\d{4})?$",
-            "type": "string"
-          },
-          "state": {
-            "pattern": "^[A-Z]{2}$",
-            "type": "string"
-          }
-        },
-        "required": [
-          "name",
-          "line1",
-          "city",
-          "state",
-          "postal_code"
-        ],
-        "type": "object"
-      },
-      "expected_quote": {
-        "additionalProperties": false,
-        "properties": {
-          "billable": {
-            "type": "boolean"
-          },
-          "cost_cents": {
-            "maximum": 9007199254740991,
-            "minimum": 0,
-            "type": "integer"
-          }
-        },
-        "required": [
-          "cost_cents",
-          "billable"
-        ],
-        "type": "object"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "mail_class": {
-        "default": "priority",
-        "enum": [
-          "priority",
-          "first_class"
-        ],
-        "type": "string"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "forward",
-        "type": "string"
-      },
-      "untracked_acknowledged": {
-        "default": false,
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version",
-      "destination"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "confirmed": {
-        "const": true,
-        "type": "boolean"
-      },
-      "expected_version": {
-        "exclusiveMinimum": 0,
-        "maximum": 9007199254740991,
-        "type": "integer"
-      },
-      "note": {
-        "maxLength": 500,
-        "type": "string"
-      },
-      "type": {
-        "const": "discard",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "expected_version",
-      "confirmed"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "expected_quote": {
+        "additionalProperties": false,
+        "properties": {
+          "billable": {
+            "type": "boolean"
+          },
+          "cost_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "cost_cents",
+          "billable"
+        ],
+        "type": "object"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "scan",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "destination": {
+        "additionalProperties": false,
+        "properties": {
+          "city": {
+            "maxLength": 80,
+            "minLength": 1,
+            "type": "string"
+          },
+          "company": {
+            "anyOf": [
+              {
+                "maxLength": 100,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null
+          },
+          "country": {
+            "const": "US",
+            "default": "US",
+            "type": "string"
+          },
+          "line1": {
+            "maxLength": 120,
+            "minLength": 1,
+            "type": "string"
+          },
+          "line2": {
+            "anyOf": [
+              {
+                "maxLength": 120,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null
+          },
+          "name": {
+            "maxLength": 100,
+            "minLength": 1,
+            "type": "string"
+          },
+          "postal_code": {
+            "pattern": "^\\d{5}(-\\d{4})?$",
+            "type": "string"
+          },
+          "state": {
+            "pattern": "^[A-Z]{2}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "line1",
+          "city",
+          "state",
+          "postal_code"
+        ],
+        "type": "object"
+      },
+      "expected_quote": {
+        "additionalProperties": false,
+        "properties": {
+          "billable": {
+            "type": "boolean"
+          },
+          "cost_cents": {
+            "maximum": 9007199254740991,
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "cost_cents",
+          "billable"
+        ],
+        "type": "object"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "mail_class": {
+        "default": "priority",
+        "enum": [
+          "first_class",
+          "priority",
+          "certified",
+          "certified_return_receipt",
+          "fedex_ground",
+          "fedex_express",
+          "fedex_2day",
+          "fedex_overnight"
+        ],
+        "type": "string"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "forward",
+        "type": "string"
+      },
+      "untracked_acknowledged": {
+        "default": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version",
+      "destination"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "confirmed": {
+        "const": true,
+        "type": "boolean"
+      },
+      "expected_version": {
+        "exclusiveMinimum": 0,
+        "maximum": 9007199254740991,
+        "type": "integer"
+      },
+      "note": {
+        "maxLength": 500,
+        "type": "string"
+      },
+      "type": {
+        "const": "discard",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "expected_version",
+      "confirmed"
+    ],
+    "type": "object"
+  }
+]

changedOutput schema / properties / result / properties / action / properties / mail_class / anyOf

Previous value: -[
-  {
-    "enum": [
-      "priority",
-      "first_class"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "first_class",
+      "priority",
+      "certified",
+      "certified_return_receipt",
+      "fedex_ground",
+      "fedex_express",
+      "fedex_2day",
+      "fedex_overnight"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

AddedSep 20, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that proposals never charge credits, buy postage, move mail, or execute the action themselves; also reveals server-side policy checks, the one-open-action constraint, required scope, and denial behavior. This prevents dangerous assumptions about immediate execution.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, but the description repeats the proposal-waits-and-never-acts point twice and restates the inbound_policy check twice. Sentences like 'Image URLs are never issued to agents' add tangential detail and bloat the text beyond what is needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers required scope, idempotency behavior, version conflicts, destination constraints, policy enforcement, concurrency limits, and denial handling. With an output schema present, it does not need to describe return values, and the description supplies enough operational detail to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Compensates for 0% schema coverage by explaining expected_version as the item's current version, idempotency_key as a stable retry key, and the US destination requirement including untracked_acknowledged for first_class. Optional fields like expected_quote and mail_class are not explained, but the core required parameters receive meaningful operational guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specifies a clear verb ('Propose'), the exact resource ('/v1/inbound-items/:id/actions'), and enumerates the three action types (scan, forward, discard). This unambiguously identifies what the tool does and distinguishes it from generic sibling operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides strong context: agent keys only, owner approval always required, policy checks on forward/discard, and a hard rule to stop on denial. It does not explicitly name alternative tools or when to prefer them, but the usage boundaries are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All mailbox tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?