Cloud Mail MCP Manual

Cloud Mail MCP — usage manual (progressive disclosure)

Cloud Mail is a REST client for a self-hosted Cloud Mail deployment, not IMAP or SMTP. Inbound mail is polled automatically and delivered to the host agent's inbox via LICC; you normally do not poll check just to receive notifications. Each notification already carries the current message (sender, subject, body preview, and an exact message_ref id) — do not call check, search, or read again merely to reread that same content or to recover an id already present in the notification; see reference/actions.md for exactly when a read recovery call is warranted. This file is the model-facing router. Load only the packaged reference that matches the question:

The references are packaged sidecars and are not embedded in the manual action result. They contain operational depth without making every ordinary call carry it.

HOW TO CALL IT — the envelope

cloud_mail is one strict LTP-v2 tool family. Every call has the closed root {action, input, reasoning, summarize?}: action, input, and reasoning are required; summarize is optional, root-level, and never nested under input. input accepts only the branch for the selected action, and validation rejects unknown or cross-action keys before manager I/O. The actions are exactly check, search, read, send, accounts, add_user, settings, and manual; settings is immediately before manual. Do not use a flat/legacy shape, _reasoning, aliases, or a generic dispatcher.

cloud_mail(action="check", input={"limit": 10}, reasoning="check recent mail")
cloud_mail(action="read", input={"id": "cloudmail:1234"}, reasoning="read this mail")
cloud_mail(action="send", input={"address": "user@example.com", "message": "done"},
           reasoning="report completion")
cloud_mail(action="settings", input={}, reasoning="inspect owner settings")

ACTIONS — first-call inventory

• check lists recent inbound mail. Optional input is account, limit, to_email, send_email, subject, time_sort, and type.
• search filters the public email list. Optional input is account, to_email, send_email, send_name, subject, content, time_sort, num, size, type, and is_del. Use the returned ids; filters are LIKE matches.
• read returns one full email. Use a returned compound id in the form <account>:<emailId>, or provide account with numeric/string email_id.
• send requires address (a recipient string or list). Supply plain text through message/text and/or HTML through html/content_html; optional fields are account, subject, name, and send_account_id. User credentials are required and attachments are not supported.
• accounts returns redacted per-account status; it does not return passwords or tokens.
• add_user requires email and password, with optional account and role_name; it is an admin operation that changes the Cloud Mail user set.
• settings is a strict-empty, read-only startup inventory. manual returns this packaged guide and its metadata on demand.

check, search, and read can return bulky listings or full bodies. Keep exact ids and body text when a later action depends on them: this family does not currently promise result summarization. Read manual exactly so its procedure and constraints remain available.

SETTINGS SHOW

settings accepts exactly input={} and returns exactly two rows, in order: config_path, then accounts. Each successful row has only key, current, default, configurable, and comment. Both rows are sensitive and render <redacted> for current and default; there is no set/reset or other mutation operation. configurable=true does not grant this action write authority. Follow reference/setup.md and the shared mcp-manual curated-addon procedure for authorized owner changes, then perform a full Cloud Mail relaunch and call SHOW again.

Config path

config_path is the exact resolved path successfully loaded at startup from LINGTAI_CLOUD_MAIL_CONFIG. It is an applied snapshot, not a fresh environment reread, and is fully redacted because it can reveal private machine layout.

Accounts document

accounts is only an opaque configured marker for the document selected by config_path; the settings provider never traverses or projects account records. It is fully redacted. Missing startup truth fails the whole inventory with the fixed SETTINGS_UNAVAILABLE result; no partial rows or startup exception are returned, and manual remains available.

SAFETY & RESULTS

• send delivers real email to real recipients: confirm recipients and body before this external, hard-to-undo side effect.
• add_user mutates the Cloud Mail deployment's user set; double-check the account, email, and role first.
• Successful business actions return status: "ok"; provider or business failures return status: "error" with an error message, while envelope, settings, or dispatch validation failures use status: "failed". Inspect the status and error fields; do not assume delivery.
• Setup fields, credential handling, watermark state, and retry/startup diagnosis are intentionally in reference/setup.md, not repeated in this resident router.