Mailbox MCP

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:

{
  "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.