fastpanel-mcp

mailbox_update

DestructiveIdempotent

Modify an existing mailbox: reset its password, change quota, toggle enabled state, or replace forwarding addresses and aliases. Use dry_run first, then confirm:true to apply changes.

Instructions

Change an existing mailbox: reset its password, enable/disable it, change quota, redirects (forwarding), aliases, save_in_box, spam_to_junk. Maps to PUT /api/mail/box/{box_id}. WRITE operation — set dry_run:true first, then confirm:true to execute. Only the fields you pass change: the tool reads the current box and re-sends the rest (the panel form PUTs the whole object). redirects and aliases REPLACE the whole list — pass the full desired list, [] to clear. Password reset: password or generate_password:true (returned ONCE as generated_password, never retrievable later). WARNING: a password reset immediately breaks every mail client / integration still using the old password — existing passwords cannot be viewed through FastPanel, only replaced. Omitting the password keeps the current one. With the local password store enabled, any new password is saved there automatically (mailbox_password_get). Async: the response has action:"UPDATING"; poll mailbox_get until action is null.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "box_id": "<box_id>"
    },
    "name": "mailbox_update"
  }
}

Input Schema

Name	Required	Description
`quota`	No	Quota in MB; 0 = unlimited
`box_id`	Yes	Mailbox id from mailboxes_list
`aliases`	No	Full replacement list of alias local parts; [] removes all
`confirm`	No	Must be true to execute. Safety guard.
`dry_run`	No	If true, show the payload that would be sent without executing.
`enabled`	No	false disables the mailbox (no login/delivery) without deleting it
`password`	No	New password (8-255 chars). Omit to keep the current one.
`redirects`	No	Full replacement list of forwarding addresses; [] removes all
`save_in_box`	No	Keep a local copy of forwarded mail. false + redirects = forward-only box.
`spam_to_junk`	No	Deliver detected spam to the Junk folder
`generate_password`	No	Reset to a strong random 24-char password and return it once in the result.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.3.0Nov 12, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Adds substantial behavior beyond the annotations: only passed fields change because the tool reads the box and re-sends the rest, redirects/aliases replace the whole list, generated passwords are returned once and never retrievable, a reset silently breaks existing mail clients, and the call is async with action:"UPDATING" requiring polling. None of that is derivable from destructiveHint/idempotentHint alone.

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?

Front-loads the operation and endpoint, then layers the dry_run/confirm workflow, per-field caveats, the password warning, and async behavior in a logical order. It is dense and long-ish, but nearly every clause carries operational consequence; the WARNING sentence is slightly redundant with the earlier password sentence.

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 an 11-parameter destructive async mutation with no output schema, it covers the mutation model, the safety handshake, one-time secret handling, list replacement, and the post-call polling requirement — everything needed to invoke and follow up correctly.

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

Parameters5/5

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

Even at 100% schema coverage the description contributes meaning the schema lacks: the merge-not-overwrite semantics for omitted fields, REPLACE semantics emphasized for the two list parameters with [] to clear, the exclusivity/danger of password vs generate_password, and the fact that a new password lands in the local store used by mailbox_password_get.

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?

Opens with a specific verb and resource ("Change an existing mailbox") and then enumerates the exact field families it touches (password, enabled, quota, redirects, aliases, save_in_box, spam_to_junk), plus the underlying endpoint PUT /api/mail/box/{box_id}. An agent can distinguish this from mailbox_create or mailbox_get purely from the first sentence.

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?

Gives an explicit operational sequence — set dry_run:true first, then confirm:true to execute — and points to mailbox_password_get for stored passwords and mailbox_get for polling. It does not, however, state when to prefer this over sibling update tools (e.g. email-domain-level updates) or any precondition/inheritance rules, so it stops short of full when/when-not coverage.

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