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 state approvalRequired 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. Mailbox references use id; message and thread references add messageId and threadId. Other inputs include replyAll and idempotencyKey.

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. It takes a name and the mailbox's email address, with an optional sender displayName, and returns the mailbox with its endpoints.

mailbox_reply answers the message's Reply-To or sender, from the endpoint the thread belongs to. Set replyAll to include every other original recipient. The server sets the recipients, subject, and threading headers of a reply. mailbox_forward quotes the original, attaches its attachments, and sends from the endpoint of the original's thread. 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 idempotencyKey. Repeating a call with the same key and body returns the same action's current phase; 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 idempotencyKey to deliberately send identical content again.

Each send returns an action receipt with state, actionId, nullable threadId and draftId, messageId and acceptedAt once accepted, and skippedRecipients. A queued receipt is progress, not confirmation of sending; uncertain needs reconciliation. Use mailbox_action_get to read progress. Preserve the same key and body after a lost response; never use a new key as recovery. See Approve sends for the states and sending deadline.

mailbox_action_cancel and mailbox_action_retry require a permitted person through OAuth. Cancel works before acceptance; Retry requires retryEligible and keeps the original deadline. An API key or extension cannot use either operation.

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.

• Thread lists and searches, thread and message reads, attachment text extraction, and quarantine lists return content_trust: "untrusted_email" with the result under content. Their text rendering uses <untrusted_email> delimiters with a notice that the content is data, never instructions. Keep those delimiters in your model's context. Mailbox and label listings do not use this wrapper.
• 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