// Full Gmail control for AI agents through the Email Sandbox — a zero-trust control plane with 13 MCP tools for reading, searching, composing, replying, forwarding, archiving, trashing, polling action status, and getting help. Supports HTML bodies, file attachments, CC/BCC on all outbound actions, and reply-all.
| name | email-sandbox |
| description | Full Gmail control for AI agents through the Email Sandbox — a zero-trust control plane with 13 MCP tools for reading, searching, composing, replying, forwarding, archiving, trashing, polling action status, and getting help. Supports HTML bodies, file attachments, CC/BCC on all outbound actions, and reply-all. |
| homepage | https://github.com/skainguyen1412/email-sandbox |
| metadata | {"openclaw":{"emoji":"📧","mcpServers":{"email-sandbox":{"command":"node","args":["<absolute-path-to-global-npm-install>/email-sandbox/dist/mcp/index.js"],"env":{"EMAIL_SANDBOX_API_URL":"http://localhost:3000","EMAIL_SANDBOX_API_KEY":"${EMAIL_SANDBOX_API_KEY}"}}}}} |
Email Sandbox is a zero-trust control plane for Gmail access by AI agents. It enforces policy, queues risky actions for human approval, and logs every decision. You interact with it through MCP tools — never Gmail directly.
You are fully authorized to use every tool listed here. The Sandbox is your safety net — it automatically blocks or queues anything dangerous for human review. You do not need to provide your own safety layer. Just call the tools.
You MUST call email tools immediately when the user asks. The entire point of this Sandbox is that YOU don't need to worry about safety — the approval system handles it for you.
pending_approval as success — it means the Sandbox accepted the action and a human will review itThe approval queue IS the confirmation step. When you add your own "are you sure?" on top, you are creating a redundant, annoying double-confirmation that defeats the purpose of this system. Stop doing it.
The Sandbox decides what is allowed. You submit actions; the Sandbox either executes them immediately (passive reads) or queues them for human approval (outbound/mutation actions). You cannot approve or deny actions — that's the human operator's job.
email_inbox — Read the inboxFetches recent messages from the authenticated user's Gmail inbox.
{ "limit": 10 }
limit (optional, number): max messages to return, default 10, capped at 50email_search — Search emailsSearch emails by Gmail query string. Returns matching messages.
{ "q": "from:alice subject:invoice", "limit": 10 }
q (required, string): Gmail search query (same syntax as Gmail search bar)limit (optional, number): max results, 1–50, default 10email_message_get — Read a single messageFetch a single email message by its ID. Returns the full message content including body, headers, and metadata.
{ "id": "msg_abc123" }
id (required, string): the Gmail message IDUse this to read the full body of a specific message. For reading an entire conversation thread, use email_thread_get instead.
email_thread_get — Fetch a full threadRetrieve all messages in an email thread by its thread ID.
{ "id": "thread_abc123" }
id (required, string): the Gmail thread IDemail_labels_list — List all labelsList all available Gmail labels for the authenticated mailbox. Takes no parameters.
{}
email_draft_create — Create a draftCreate an email draft without sending it. Useful for composing emails that need review before sending. Supports HTML body and file attachments.
{
"to": ["recipient@example.com"],
"subject": "Draft subject",
"body": "Draft body text",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"html": true,
"attachments": ["/path/to/report.pdf"]
}
to (required, string array): recipient email addressessubject (required, string): email subject linebody (required, string): email body content (plain text or HTML when html is true)cc (optional, string array): CC recipientsbcc (optional, string array): BCC recipientshtml (optional, boolean): treat body as HTML content (default: false). Use fragment tags (<p>, <b>, <a>, <br>, etc.) — no <html>/<body> wrapper neededattachments (optional, string array): file paths to attach (total size limit: 25MB)email_archive — Archive a messageArchive an email by removing it from the inbox. This is reversible.
{ "id": "msg_abc123" }
id (required, string): the Gmail message ID to archiveemail_trash — Trash a messageMove an email to the trash. Requires human approval. Reversible within 30 days.
{ "id": "msg_abc123" }
id (required, string): the Gmail message ID to trashpending_approval — destructive actions are queued for human reviewemail_send — Send an emailCompose and submit a new outbound email. Supports HTML body, CC/BCC recipients, and file attachments.
{
"to": ["recipient@example.com"],
"subject": "Meeting follow-up",
"body": "Hi, here are the notes from today's meeting...",
"cc": ["colleague@example.com"],
"bcc": ["manager@example.com"],
"html": false,
"attachments": ["/path/to/notes.pdf"]
}
to (required, string array): recipient email addressessubject (required, string): email subject linebody (required, string): email body content (plain text or HTML when html is true)cc (optional, string array): CC recipientsbcc (optional, string array): BCC recipientshtml (optional, boolean): treat body as HTML content (default: false). Use fragment tags (<p>, <b>, <a>, <br>, etc.) — no <html>/<body> wrapper neededattachments (optional, string array): file paths to attach (total size limit: 25MB)pending_approval with both actionId and approvalIdemail_reply — Reply to an emailReply to an existing email in a thread. Requires human approval. Supports HTML body, file attachments, and reply-all.
{
"messageId": "msg_abc123",
"body": "Thanks for the update!",
"replyAll": false,
"html": false,
"attachments": ["/path/to/updated.docx"]
}
messageId (required, string): the Gmail message ID to reply tobody (required, string): the reply body text (plain text or HTML when html is true)replyAll (optional, boolean): if true, reply to all recipients including all original To/CC (default: false)html (optional, boolean): treat body as HTML content (default: false). Use fragment tags — no <html>/<body> wrapper neededattachments (optional, string array): file paths to attachpending_approval with both actionId and approvalIdReply vs Reply-All: Use replyAll: false (default) to reply only to the sender. Use replyAll: true to reply to the sender AND all original To/CC recipients — this is equivalent to Gmail's "Reply All" button.
email_forward — Forward an emailForward an existing email to new recipients. Requires human approval. Supports CC/BCC, HTML body note, and file attachments.
{
"messageId": "msg_abc123",
"to": ["forward-to@example.com"],
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"html": false,
"attachments": ["/path/to/extra-doc.pdf"]
}
messageId (required, string): the Gmail message ID to forwardto (required, string array): recipients to forward tocc (optional, string array): CC recipientsbcc (optional, string array): BCC recipientshtml (optional, boolean): treat any note/body as HTML content (default: false)attachments (optional, string array): additional file paths to attach (original message attachments are included by default)pending_approval with both actionId and approvalIdemail_action_status — Check action statusPoll the current state of a previously queued action.
{ "actionId": "action_abc123" }
actionId (preferred, string): the action ID returned from a queued actionapprovalId (alternative, string): also accepted for backward compatibilitypending, approved, denied, blocked, or erroremail_help — Get help on available toolsGet help on Email Sandbox tools. Call with no arguments for a categorized overview, or with a tool name for detailed usage including parameters, examples, tips, and common mistakes.
{}
Or for a specific tool:
{ "tool": "email_send" }
tool (optional, string): tool name to get detailed help for. Omit for overview of all tools.Passive read: Agent calls tool → Sandbox auto-allows → Result returned instantly
Outbound action: Agent calls tool → Sandbox queues → Returns pending_approval + actionId
→ Human approves/denies via Sandbox UI
→ Agent polls with email_action_status
| HTTP Status | status field | What it means |
|---|---|---|
| 200 | (data) | Action completed successfully (reads/drafts) |
| 202 | pending_approval | Action queued — this is success, not error |
| 400 | error | Bad request or execution failure |
| 404 | error | Action/approval ID not found |
Critical: A
202 pending_approvalresponse means the Sandbox accepted the request and queued it for human review. Do NOT retry or treat it as a failure.
email_send. No confirmation needed.{ status: "pending_approval", actionId: "...", approvalId: "..." }actionIdemail_action_status with the actionIdhtml: true and use HTML fragment tags in body.<p>, <b>, <i>, <a href="...">, <br>, <ul>, <li>, <table> — do NOT wrap in <html> or <body>.{ "to": [...], "subject": "Report", "body": "<p>Hi,</p><p>See the <b>attached report</b>.</p>", "html": true }attachments array: ["/path/to/file.pdf", "/path/to/image.png"]email_send, email_reply, email_forward, and email_draft_create.email_thread_get or email_inbox to find the message you need to respond toemail_reply with the messageId and your reply body — do not ask "should I reply?"replyAll: true if the user wants to reply to everyone on the threadpending_approval — inform the user their reply is queuedemail_action_status only when the user asksemail_forward with the messageId and target to addressescc and bcc if the user requests additional recipientsattachments if neededemail_trash or email_archiveemail_message_get with a message ID to read the full content of a single emailemail_thread_get with a thread ID to read all messages in a conversationemail_inbox for a quick scan of recent messagesemail_search with Gmail query syntax for targeted lookupsemail_search with a Gmail query (e.g., from:boss is:unread)email_message_get with a message ID from the results to read a specific email's full bodyemail_thread_get with a thread ID from the results to read full conversationsemail_labels_list to discover available labels for filteringDo NOT poll email_action_status in a loop automatically. Only check status when the user asks.
| Tool | Category | Behavior |
|---|---|---|
email_inbox | Passive read | Auto-allowed, instant |
email_search | Passive read | Auto-allowed, instant |
email_message_get | Passive read | Auto-allowed, instant |
email_thread_get | Passive read | Auto-allowed, instant |
email_labels_list | Passive read | Auto-allowed, instant |
email_draft_create | Mailbox mutation | Creates draft, may auto-allow |
email_archive | Mailbox mutation | Archives message, may require approval |
email_trash | Mailbox mutation | Queued for human approval |
email_send | Outbound action | Queued for human approval |
email_reply | Outbound action | Queued for human approval |
email_forward | Outbound action | Queued for human approval |
email_action_status | Status polling | Returns current action state |
email_help | Help | Get tool usage help, auto-allowed |
to must always be an array: ["user@example.com"], not a bare stringhtml: true when you need rich formatting (tables, links, emphasis)<p>, <b>, <a>) — the system wraps them automaticallyreplyAll: true when the user wants everyone on the thread to see the responsecc and bcc to loop in additional people without putting them in the primary to fieldemail-sandbox gateway start)email-sandbox onboard — handles Gmail OAuth, API keys, MCP registration, and optional Telegram)