# arbengine/mailbox-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/arbengine/mailbox-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1002  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/arbengine-mailbox-mcp

## Description
Physical mail API for AI agents. Send letters, certified mail, postcards, and batch mailings with cost previews, approval controls, tracking, and webhooks.

## Tools
Capabilities this server exposes over MCP:

- **send_email** — Send a new email. Refuses new recipients without confirm_new_recipient, and creates a draft instead on accounts configured draftsOnly.
- **reply_email** — Reply to an email message. Extra cc/bcc addresses the account has never written to need confirm_new_recipient. On draftsOnly accounts a reply draft is created instead.
- **forward_email** — Forward an email message to new recipients. Forwarding outside the account's own domain needs confirm_external_forward; recipients the account has never written to need confirm_new_recipient. On draftsOnly accounts a forward draft is created instead.
- **create_draft** — Create a draft email
- **list_accounts** — List all configured email accounts with their provider type and email address
- **authenticate** — Add a new email account. Refuses an alias that already exists (edit accounts.json or use reauth). For Gmail: opens a browser for OAuth. For IMAP/JMAP: stores encrypted credentials. Sensitive fields (username, password) can also be set via environment variables.
- **reauth** — Re-run OAuth for an existing Gmail account without removing it. Opens a browser for Google sign-in. Use when the refresh token expires (invalid_grant) or scopes change.
- **remove_account** — Remove a configured email account and its stored credentials. Refuses for an account with any safety setting; those are removed by editing accounts.json.
- **search_emails** — Search emails in an account. Gmail supports full Gmail search syntax. IMAP searches subject and body. Optional folder parameter scopes the search to a specific label/folder.
- **read_email** — Read a single email message with full content
- **read_thread** — Read an entire email conversation thread (Gmail and JMAP only)
- **inbox_summary** — Get a summary of recent inbox activity including total and unread counts. When a TypeSafe API key is configured, each recent message is also triaged (needs reply, FYI, newsletter, receipt, notification, suspicious) by the Jev decision model.
- **list_labels** — List all labels (Gmail) or folders (IMAP) for an account
- **create_label** — Create a new label (Gmail) or folder (IMAP)
- **delete_label** — Delete a label (Gmail) or folder (IMAP)
- **modify_email** — Add or remove labels/flags on a message
- **batch_modify_emails** — Add or remove labels/flags on multiple messages
- **trash_emails** — Move messages to trash
- **bulk_trash** — Trash all messages matching a query. Paginates the search and batch-trashes the IDs in one call. Use dry_run to see the count before committing. Useful for label cleanups (e.g. trash everything in 'Newsletters' or older than 90 days).
- **bulk_modify** — Add or remove labels on all messages matching a query. Same fast search-then-batch pattern as bulk_trash, but for arbitrary label ops. Use this for archive (remove_labels=['INBOX']), bulk star/unstar, mark-read across a label, moving messages between labels, etc. Use dry_run to see the count first.
- **list_recent_bulk_ops** — List recent bulk_modify and bulk_trash operations recorded in the transaction log. Use to find an op id for undo_bulk_op.
- **undo_bulk_op** — Reverse a previously recorded bulk_modify or bulk_trash by replaying the inverse label change against the exact ids that were touched. Find the op id from list_recent_bulk_ops. Idempotent on already-reversed ops (refuses to re-reverse).
- **list_filters** — List Gmail filters
- **create_filter** — Create a Gmail filter
- **delete_filter** — Delete a Gmail filter
- **save_template** — Save an email template (stored as a Gmail draft with TEMPLATE label)
- **list_templates** — List saved email templates
- **delete_template** — Delete a saved template
- **send_template** — Send an email using a saved template
- **get_signature** — Get the email signature for a Gmail account
- **set_signature** — Update the email signature for a Gmail account
- **get_vacation** — Get vacation auto-reply settings
- **set_vacation** — Configure vacation auto-reply
- **unsubscribe** — Unsubscribe from a mailing list by finding the List-Unsubscribe header
- **bulk_unsubscribe** — Find unsubscribe links for multiple mailing list messages
- **update_draft** — Replace the contents of an existing Gmail draft. The draft's thread association is preserved automatically.
- **delete_draft** — Permanently delete a Gmail draft. This cannot be undone.
- **list_send_as** — List send-as aliases configured on a Gmail account
- **download_attachment** — Download an email attachment to a safe directory
- **mark_read** — Mark an email as read or unread
- **star_email** — Star or unstar an email
- **archive_email** — Archive an email (remove from inbox). Gmail removes the INBOX label; IMAP moves to the Archive folder; JMAP moves out of the inbox mailbox.
- **list_drafts** — List drafts for an account
- **send_draft** — Send an existing draft as-is. Runs the same recipient guards as send_email. For Gmail/JMAP the draft is finalised and submitted; for IMAP the message is sent via SMTP and removed from the Drafts folder.
- **count_unread_by_label** — Count unread messages per label/folder. Useful for deciding where to look first.
- **emails_since** — List messages received after a given timestamp. Use for polling new mail since a last-check marker.
- **multi_account_search** — Run the same search across all configured accounts in parallel. Returns results grouped by account alias.
- **export_email** — Export an email as a raw RFC 822 .eml file to a safe directory. Useful for archival, legal discovery, or migration.
- **export_thread** — Export all messages in a thread as individual .eml files to a safe directory. Gmail/JMAP only.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mailbox-mcp": {
    "command": "npx",
    "args": ["-y","mailbox-mcp"]
  }
}
```

## Documentation

## What arbengine/mailbox-mcp does

arbengine/mailbox-mcp exposes mailbox.bot's physical-mail operations through MCP. Agents can price and send letters, postcards, document packets, and batch campaigns, then inspect statuses, costs, refunds, tracking details, and fulfillment photos. Plain-text letters use the same outbound workflow as document-based sends.

The service also provides a mailbox at a staffed, USPS-compliant facility in Manhattan Beach, California. The address includes a street address and PMB, with the PMB assigned after USPS Form 1583 verification. Inbound features include forwarding aliases, forwarded scans and PDFs, OCR-backed item details, page text, postal threads, and actions such as scanning, forwarding, or discarding mail.

## How it works

The production endpoint is `https://mailbox.bot/api/mcp`, using Streamable HTTP. Clients can authenticate through MCP sign-in, or send a bearer key in the `Authorization` header. A live agent key can send physical mail and spend prepaid credits; a sandbox key uses the same endpoint without charges or physical fulfillment. Member account keys cannot send mail.

Outbound operations are designed around preview and approval. `quote_outbound_mail` prices a letter before its document exists, while `send_outbound_mail` supports `dry_run=true` to return the applicable cost. Batch workflows estimate pricing, create an uncharged draft, produce a proof link, and then use `confirm_batch_mail` to pay and queue the batch. Approval policies, daily-piece limits, and `max_cost_cents` can prevent an unintended debit.

Sandbox tools create test records and advance them through simulated states. Live mail uses prepaid credits, while agents can read balances and usage events but cannot purchase credits through the tools.

## Setup and configuration

Customers do not run a local process. Add the hosted endpoint to an MCP client and either use sign-in or configure a bearer key:

```json
{
  "mcpServers": {
    "mailbox-bot": {
      "url": "https://mailbox.bot/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_agent_YOUR_KEY_HERE"
      }
    }
  }
}
```

Accounts are created through mailbox.bot. The repository also provides Cursor and Claude Code plugin configuration. Live mailbox rentals cost $15 per month; outbound mail uses prepaid credits and has no monthly base fee. Forwarding aliases use the `forward.mailbox.bot` domain and are intended for scans, photos, and PDFs from an address the operator already controls.

## Tools and capabilities

The current tool set includes capabilities for:

- Reading mailbox details, usage, credit balances, inbound items, OCR text, pages, and postal timelines.
- Sending facility messages and reading facility conversations.
- Pricing, previewing, sending, listing, inspecting, and cancelling outbound mail.
- Creating text letters and batch drafts from PDF or image templates with inline recipients or CSV links.
- Reviewing one-hour batch proof PDFs before confirmation.
- Applying full batch cancellation refunds before facility processing begins.
- Creating and advancing sandbox outbound and batch records.
- Managing webhook endpoints, event subscriptions, tests, delivery history, retries, and signing-secret rotation.
- Reading and proposing changes to versioned `MAILBOX.md` instructions.

## Limitations and notes

The PMB is assigned only after USPS Form 1583 verification. Live sends consume prepaid credits and may require owner approval. Cancellation refunds depend on the outbound job still being queued; batch cancellation is available before the facility starts processing. Sandbox keys see sandbox data only, including the account's sample letter, and do not produce physical mail. Several older agent-inbox tools remain available as deprecated aliases, with newer inbound-item tools preferred.

_Full upstream README: https://allmcps.com/mcp/arbengine-mailbox-mcp/readme_