mailbox.bot

MCP Install

mailbox.bot MCP Server

Copy full docs

Connect any MCP-capable AI client to mailbox.bot using Model Context Protocol (MCP). Your agent gets 30 tools for inbound context, package management, scans, facility messages, outbound mail, standing instructions, and webhooks.

Inbound context loop

Use list_inbound_forwarding_addresses to discover the renter's private alias on forward.mailbox.bot. Forward or email scans, PDFs, photos, provider notices, and notes to that alias to initiate OCR/extraction. Then use list_inbound_mail or get_inbound_mail to retrieve draft_context for your LLM, and pass inbound_capture_id / postal_mail_thread_id into send_outbound_mail when the generated reply becomes physical mail. After a successful send, use document_preview_url for human visual verification of the submitted document.

Hosted MCP endpoint

URL: https://mailbox.bot/api/mcp

Transport: Streamable HTTP

Auth: Authorization: Bearer YOUR_API_KEY

Outbound mail safety

send_outbound_mail can create paid physical mail when used with a production key. Keep fast workflows fast, but use one explicit safeguard before live sends.

1. Use dry_run=true for no-credit-debit validation, page count, mail class, and exact cost preview.

2. Use requires_approval=true when a human should review first. Approval-first submissions return document_preview_url and do not spend credits until dashboard approval.

3. Show human_review before a live funded send or dashboard approval. Confirm send-to address, return address, mail class, document filename, page count, cost, safeguards, and preview URL when present.

4. In Cursor chat, answer credit questions with get_usage. Tell the human the prepaid balance and that only they can add funds from dashboard billing.

5. For “cancel this order,” identify the outbound mail record, call cancel_outbound_mail while it is still submitted, then report cancellation status, returned credits, updated balance, and whether it was already cancelled. If a transient error occurs, poll the mail record and credits before retrying.

6. Use max_cost_cents, force_approval keys, and sk_agent_test_ sandbox keys for repeated testing or agent-built workflows.

1. Get your API key

Copy an sk_agent_ key for agent use, or an sk_agent_test_ key for sandbox testing. You can also use an account sk_live_ key during setup. Get keys from the dashboard, then paste one below to fill the examples.

2. Choose your MCP client

HTTPBridgeClaude CodeClaude DesktopCursorVS CodeWindsurfn8n

Add this block to any MCP client that supports remote HTTP servers: Use https://mailbox.bot/api/mcp as the server URL and pass your API key in the Authorization header. If your client expects a local command instead of a remote URL, use the command bridge preset.

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

Copy

Troubleshooting

Client cannot reach the remote server

Switch to the Bridge preset. It runs mcp-remote locally and connects to the same hosted endpoint.

npx or Node is missing

Install Node.js LTS, restart the client, then refresh MCP servers. Command-bridge presets require npx.

Tools do not appear after saving

Restart the client or use its MCP server refresh action. Some clients only load MCP servers at startup.

3. Reload your MCP client

Restart or reload your client so it discovers the mailbox.bot tools. Ask your agent to list packages, request a scan, send facility messages, or create outbound mail.

Available MCP Tools (30)

get_mailboxlist_packagesget_packageget_package_photosrequest_actionrequest_scanget_scan_resultsadd_tagadd_notecreate_ruleregister_expectedget_usagelist_inbound_forwarding_addresseslist_inbound_mailget_inbound_maillist_postal_threadsget_postal_threadupdate_actionget_mailbox_mdpropose_mailbox_md_editsend_facility_messagelist_facility_conversationsget_facility_messagesupdate_webhooksend_outbound_maillist_outbound_mailget_outbound_mailcancel_outbound_mailcreate_test_outbound_mailadvance_test_outbound_mail

Other ways to integrate

API

REST API docs →OpenAPI spec (JSON) →OpenAPI spec (YAML) →

Discovery

A2A standard agent card →A2A agent card →Multi-protocol discovery →Documentation index →Full LLM reference + support →

Source

Hosted MCP app source →Agent instruction skill →Public MCP tool catalog →Smithery directory →