fastpanel-mcp

mailbox_create

Create an email mailbox on a FastPanel domain, with optional aliases, forwarding, quota, spam handling, and one-time generated passwords.

Instructions

Create a mailbox in an email domain. Maps to POST /api/email/domains/{domain_id}/boxs. WRITE operation — set dry_run:true first, then confirm:true to execute. Pass either password or generate_password:true (recommended): the generated password is returned ONCE in the result as generated_password and can never be read back afterwards (FastPanel keeps only a hash) — store it in a password manager immediately. If the local password store is enabled (FASTPANEL_PASSWORD_STORE=keychain) the password — generated or explicit — is also saved there automatically and stays retrievable via mailbox_password_get. redirects forwards incoming mail to other addresses; with redirects set, save_in_box decides whether a copy also stays in this box. aliases are extra local parts on the same domain delivering to this box. Async: the response comes back with action:"CREATING" and the box becomes usable a second or two later (mailbox_get shows action:null when done).

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>",
      "login": "<login>"
    },
    "name": "mailbox_create"
  }
}

Input Schema

Name	Required	Description
`login`	Yes	Local part before the @, e.g. 'support' for support@example.com
`quota`	No	Mailbox quota in MB (rendered as dovecot quota_rule bytes=<n>M); 0 = unlimited
`aliases`	No	Alias local parts on the same domain, e.g. ['info','hello']
`confirm`	No	Must be true to execute. Safety guard.
`dry_run`	No	If true, show the payload that would be sent without executing.
`password`	No	Mailbox password (8-255 chars). Omit when generate_password is true.
`domain_id`	Yes	Email domain id from email_domains_list
`redirects`	No	Forward incoming mail to these addresses
`save_in_box`	No	Keep a local copy when redirects are set. Default: true if redirects are given (false would make the box forward-only).
`spam_to_junk`	No	Deliver detected spam to the Junk folder (panel default for existing boxes)
`generate_password`	No	Generate 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.5/5.0

Behavior5/5

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

Well beyond the annotations, it discloses that the generated password is returned exactly once and is unrecoverable afterwards (the panel stores only a hash), that a password store may also persist it, and that the operation is asynchronous — returning action:'CREATING' with usability a second or two later and mailbox_get showing action:null when done. These are non-obvious, high-consequence behaviors an agent cannot get from readOnly/openWorld hints.

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?

Purpose and the safety two-step are front-loaded, and nearly every clause carries operational information. It is a dense single block, though, so the password-handling and redirect/alias semantics would be easier to scan if structured; 'WRITE operation' is also slightly redundant with readOnlyHint:false.

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 mutation with no output schema and asynchronous completion, the description covers the safety guard, the one-time secret exposure, side effects on the local password store, forwarding/alias semantics, and the eventual-consistency window. An agent has everything needed to call it correctly and to handle the result safely.

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; the description lifts it by adding cross-parameter meaning the schema does not express — the either/or relationship between password and generate_password, the recommendation for generated passwords, the fact that redirects plus save_in_box determines whether a copy is retained, and how aliases relate to the domain. It stops short of covering every parameter (quota, spam_to_junk) in prose, but those are already well documented in the schema.

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

Purpose4/5

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

The first sentence gives a precise verb+resource ('Create a mailbox in an email domain') and the endpoint mapping (POST /api/email/domains/{domain_id}/boxs) confirms scope. It is clearly separable from mailbox_get and mailbox_update by verb, but it never explicitly states the boundary against those siblings, leaving that to name inference.

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

Usage Guidelines5/5

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

It spells out the exact call sequence (dry_run:true first, then confirm:true to execute) and the mutually exclusive input choice (password vs generate_password:true, with the latter recommended). It also routes to mailbox_password_get for later retrieval and explains when to use redirects vs aliases, so the agent knows both when and how to invoke it.

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