mailbox-mcp

create_webhook_endpoint

Idempotent

Register a public HTTPS webhook endpoint to receive signed mailbox event notifications, with optional keyword rules, and return the signing secret once.

Instructions

Create a webhook: name, public HTTPS URL, events (inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched) and optional keyword rules (literal terms, any/all, exclusions). Active on save. Returns the whsec_ signing secret once; hand it only to the operator's secure configuration, never logs or mail content. Requires explicit user intent for the URL. Agent keys must use their own agent_id and environment; member keys may use agent_id:null for account scope. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints. Reuse the exact idempotency_key and input after an uncertain mutation. Webhook docs: https://mailbox.bot/docs/webhooks.

Input Schema

Name	Required	Description
`url`	Yes	Public HTTPS URL on port 443 (no credentials, fragment or private host) that receives the signed POSTs. Set or change it only on the operator's explicit instruction.
`name`	Yes	Label shown in the dashboard and delivery log.
`rules`	Yes	Up to 10 keyword rules, each with a unique id: source (envelope, letter for the contents, or any), match (any or all), 1–20 terms and optional exclude_terms. inbound.keywords_matched fires when a rule matches.
`agent_id`	Yes	Agent keys: your own agent id. Member keys: an agent id, or null for account scope.
`environment`	Yes	live or test. Agent keys must use their own environment; an endpoint only receives events from its environment.
`event_types`	Yes	Events to deliver (1–32, unique). Inbound mail: inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched. Outbound mail: mail.pending_approval, mail.submitted, mail.ready, mail.mailed, mail.delivered, mail.failed, mail.cancelled. Batches: batch.submitted, batch.completed, batch.partially_completed, batch.failed, batch.cancelled.
`idempotency_key`	Yes	A new UUID for this one intent; reuse it only to retry the identical request.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.0.4Oct 26, 2026

changedInput schema / properties / event_types / description

Previous value: -"Events to deliver (1–16, unique): inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched."New value: +"Events to deliver (1–32, unique). Inbound mail: inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched. Outbound mail: mail.pending_approval, mail.submitted, mail.ready, mail.mailed, mail.delivered, mail.failed, mail.cancelled. Batches: batch.submitted, batch.completed, batch.partially_completed, batch.failed, batch.cancelled."

changedInput schema / properties / event_types / items / enum

Previous value: -[
-  "inbound.received",
-  "inbound.action.requested",
-  "inbound.action.completed",
-  "inbound.pages_ready",
-  "inbound.keywords_matched"
-]New value: +[
+  "inbound.received",
+  "inbound.action.requested",
+  "inbound.action.completed",
+  "inbound.pages_ready",
+  "inbound.keywords_matched",
+  "mail.pending_approval",
+  "mail.submitted",
+  "mail.ready",
+  "mail.mailed",
+  "mail.delivered",
+  "mail.failed",
+  "mail.cancelled",
+  "batch.submitted",
+  "batch.completed",
+  "batch.partially_completed",
+  "batch.failed",
+  "batch.cancelled"
+]

changedInput schema / properties / event_types / maxItems
```
Previous value: -16New value: +32
```

changedOutput schema / properties / result / properties / endpoint / properties / event_types / items / enum

Previous value: -[
-  "inbound.received",
-  "inbound.action.requested",
-  "inbound.action.completed",
-  "inbound.pages_ready",
-  "inbound.keywords_matched"
-]New value: +[
+  "inbound.received",
+  "inbound.action.requested",
+  "inbound.action.completed",
+  "inbound.pages_ready",
+  "inbound.keywords_matched",
+  "mail.pending_approval",
+  "mail.submitted",
+  "mail.ready",
+  "mail.mailed",
+  "mail.delivered",
+  "mail.failed",
+  "mail.cancelled",
+  "batch.submitted",
+  "batch.completed",
+  "batch.partially_completed",
+  "batch.failed",
+  "batch.cancelled"
+]

changedOutput schema / properties / result / properties / endpoint / properties / event_types / maxItems
```
Previous value: -16New value: +32
```

Addedv1.0.3Oct 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses that the endpoint is active on save, that the whsec_ signing secret is returned exactly once and must go only to the operator's secure config and never into logs or mail content, and that authorization follows the same bounded control plane and tenant/agent/Live-Sandbox model as the HTTP API. This is exactly the kind of consequence and safety context annotations cannot express.

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

Conciseness4/5

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

The most important facts are front-loaded in the opening sentence, and the later sentences on the secret, permissions and idempotency each earn their place. It is somewhat dense and partially re-states event names already enumerated in the schema, which keeps it from being maximally tight.

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?

For a 7-required-parameter mutation with an output schema, the description covers the remaining unknowns: permissions, tenant/environment scoping, one-time secret handling, idempotent retry behavior and a docs link. Return values need not be explained because the output schema exists.

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?

Schema coverage is 100%, so the baseline is 3, but the description still adds meaning: it groups the event types into inbound/outbound/batch and spells out the agent-key versus member-key scoping rule. The keyword-rule semantics (literal terms, any/all, exclusions) are summarized here with detail that complements rather than repeats the schema.

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?

It states a specific verb and resource ('Create a webhook') and immediately enumerates the configuration surface: name, public HTTPS URL, event types and keyword rules. An agent can see the intent and scope without opening the schema, and the mention of the one-time signing secret distinguishes it from the list/get webhook siblings.

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?

It gives real operational conditions: requires explicit user intent for the URL, requires webhook.manage, agent keys must use their own agent_id and environment while member keys may pass null for account scope, and the idempotency_key must be reused after an uncertain mutation. It does not, however, name an alternative such as update_webhook_endpoint or rotate_webhook_endpoint_secret, so the agent must infer when to modify rather than create.

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

Deploy Server