fastpanel-mcp

mailboxes_list

Read-onlyIdempotent

Lists mailboxes for a FastPanel email domain, showing address, enabled status, size, quota, forwarding, aliases, and spam settings. Use it to inspect existing boxes; passwords are not returned.

Instructions

List mailboxes of one email domain: address, enabled, size (bytes used), quota, redirects (forwarding targets), aliases, save_in_box (keep a local copy when forwarding), spam_to_junk. Maps to GET /api/email/domains/{domain_id}/boxs (sic — 'boxs'). Passwords are NOT returned: FastPanel exposes no API/CLI path to read a mailbox password back (it keeps a one-way IMAP hash plus a reversible copy only the panel process itself can decrypt). To give someone access to an existing box, reset it with mailbox_update generate_password:true. When the local password store is enabled (FASTPANEL_PASSWORD_STORE), each box also carries password_stored — true means mailbox_password_get can return its password.

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": {
      "domain_id": "<domain_id>"
    },
    "name": "mailboxes_list"
  }
}

Input Schema

Name	Required	Description	Default
`compact`	No	Return essential fields only (default). false = full objects incl. owner.
`domain_id`	Yes	Email domain id from email_domains_list

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.3.0Nov 12, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations it discloses a real behavioral constraint: passwords are never returned and why (one-way IMAP hash plus a panel-only reversible copy), and it names the workaround. It also documents the conditional password_stored field tied to FASTPANEL_PASSWORD_STORE.

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 list purpose and the returned fields, then a clearly scoped caveat paragraph on passwords. The parenthetical '(sic — boxs)' endpoint note is mildly extraneous but the rest earns its space.

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?

With no output schema, the description compensates by enumerating the returned fields and their meaning (size in bytes used, redirects as forwarding targets, save_in_box, spam_to_junk). Combined with the password caveat, an agent has everything needed to call and interpret it.

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

Parameters3/5

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

Schema description coverage is 100%, so the compact/domain_id parameters are already documented, including the domain_id provenance from email_domains_list. The description's field list describes outputs rather than adding parameter meaning, so baseline 3 applies.

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?

States a specific verb and resource plus scope ('List mailboxes of one email domain') and enumerates the returned fields, so an agent knows exactly what comes back versus a single-mailbox tool like mailbox_get.

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 concrete routing for the password problem: to grant access to an existing box use mailbox_update with generate_password:true, and when password_stored is true use mailbox_password_get. It does not explicitly contrast this list call with mailbox_get for a single box, so it falls just short of full when/when-not guidance.

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