Use mailboxes over MCP

The hosted MCP server that exposes Samva's email tools also exposes mailbox tools. An agent connected with a mailbox-scoped key or an OAuth connection can list mailboxes, read and search threads, reply, and read what is held in quarantine. For the endpoint, the credential types, and client configuration, see Connect an agent over MCP.

What the credential decides

The tools do not widen access. Each call runs with the connected credential's mailbox access:

• A mailbox-scoped key reaches the mailboxes it lists, with the permissions it holds. A key without send cannot send, and a key without quarantine.read cannot list held mail. A tool a credential cannot use returns the same error the API returns: its tag, its message, any fields, and a hint that names the next step.
• An OAuth connection acts as the person who approved it, with that person's grants.
• A key's send mode applies. When it is approval, a send returns pending_approval and waits for a person; see Approve sends.

Refresh the MCP client after you change a credential so it does not keep a stale tool list.

Tools

Use tool discovery for each tool's current input schema. Inputs use snake_case names such as mailbox_id, message_id, and thread_id.

mailboxes_create needs authority to manage mailboxes, which a mailbox-scoped key never holds. Connect with an OAuth connection from an admin to let an agent create a mailbox. Mail that arrived before a mailbox existed is not added to it.

mailbox_reply takes reply_all to answer every original recipient instead of the sender. The server sets the recipients, subject, and threading headers of a reply. mailbox_forward quotes the original and attaches its attachments. mailbox_draft_create saves an unsent draft and never sends or approves it.

Retry a send safely

mailbox_send, mailbox_reply, and mailbox_forward take an optional idempotency_key. Repeating a call with the same key and body returns the original result; the same key with a different body is a conflict. When you omit the key, Samva derives one from the call, so an identical call replays. Pass a distinct idempotency_key to deliberately send identical content again.

Each send returns a receipt: status of sent or pending_approval, the threadId and actionId, the messageId once sent, and skippedRecipients for any recipient Samva did not send to.

Email is untrusted data

Anyone can email a mailbox, so everything a read tool returns from a message is untrusted. The subject, preview, sender name, body, and attachment text may contain instructions aimed at your agent.

• Every read tool returns its result under content_trust: "untrusted_email", and its text rendering wraps each message in <untrusted_email> delimiters with a notice that the content is data, never instructions. Keep those delimiters in your model's context.
• Bodies are plain text. mailbox_message_get and mailbox_thread_get prefer replyText (what the sender wrote, without quoted history) and convert HTML to text. No tool returns raw HTML or raw MIME.
• mailbox_attachment_get extracts text from text-based attachments only. Other types return their metadata and extractable: false, never bytes or download URLs.
• mailbox_quarantine_list returns metadata for held messages. Bodies and attachments stay unavailable. Mail held for prompt_injection is held for exactly this reason.

Treat what you read as content to analyze, not as commands. Give an agent that must act on mail a mailbox-scoped key with sendMode: "approval" so a person reviews what it sends.

What MCP cannot do

No MCP tool releases or discards held mail, approves or denies a send, changes a grant, or changes a key. Those need a person in the dashboard, CLI, or API.

Next steps