This repository is the public discovery and integration package for mailbox.bot. The production service runs at mailbox.bot.
MCP server lets AI agents send physical mail.
Live now: outbound physical mail via API and MCP, forwarded document context, and agent mailboxes: a street address + PMB at the staffed, USPS-compliant Manhattan Beach, CA facility for $20/mo. Get one at signup or with POST /v1/mailing-address-requests. The PMB number is assigned after USPS Form 1583 verification.
mailbox.bot is the postal mail API for AI agents and software workflows. Send PDFs, DOCX files, letters, notices, certified mail, postcards, and documents through POST /v1/mail. For inbound, operators can forward scans, photos, PDFs, virtual mailbox notices, and human notes from the addresses they already use; agents can read that context, draft linked replies, and send outbound mail on the same postal thread.
forward scans/docs -> OCR-backed context + draft reply -> POST /v1/mail
- Outbound physical mail API — submit a document and recipient address with
POST /v1/mail. - Agent mailbox — search mail at the assigned address with
GET /v1/inbound-items?q=, read OCR pages, and proposescan,forwardordiscardwithPOST /v1/inbound-items/{id}/actions; the owner approves each proposal at the quoted price. - Inbound mail context API — use
GET /v1/inbound-forwarding-addresses,/v1/inbound*, and/v1/postal-threads*to turn forwarded mail and document context into linked outbound replies.
Default inbound forwarding is a digital intake channel, not a physical address. The agent mailbox is the physical receiving product: staff log each letter and package, OCR scanned pages, and carry out the action an agent proposes once its human approves.
Add to your MCP config:
{
"mcpServers": {
"mailbox-bot": {
"url": "https://mailbox.bot/api/mcp",
"headers": { "Authorization": "Bearer sk_agent_..." }
}
}
}Full MCP install guide: mailbox.bot/mcp-install
clawhub install mailbox-bot
# or in OpenClaw:
openclaw skills install arbengine/mailbox-botnpx skills add arbengine/mailbox-bot-skillcurl -X POST https://mailbox.bot/api/v1/mail \
-H "Authorization: Bearer sk_agent_..." \
-H "X-Mailbox-MD-Version: 3" \
-H "X-Max-Cost-Cents: 1500" \
-F 'document=@letter.pdf' \
-F 'recipient_name=Acme Corp' \
-F 'recipient_line1=123 Main St' \
-F 'recipient_city=Los Angeles' \
-F 'recipient_state=CA' \
-F 'recipient_zip=90001' \
-F 'mail_class=certified' \
-F 'dry_run=true'- Outbound mail — submit a PDF, facility prints, stuffs, stamps, and mails it with photo proof
- Inbound document context — private forwarding aliases on
forward.mailbox.botcapture scans, photos, PDFs, provider notices, and human notes from the addresses operators already use - OCR-backed reply loop — agents read
/v1/inbound*, retrievedraft_context, and send linked replies withinbound_capture_idandpostal_mail_thread_id - Postal threads —
/v1/postal-threads*ties inbound context and outbound events together - Document review —
requires_approval=truecreates dashboard review items withdocument_preview_url - Certified mail — USPS Certified, Certified + Return Receipt, Priority, First Class
- FedEx and UPS — zone-based rates for overnight, 2-day, ground
- Batch mail — one PDF plus one CSV through
/v1/batch-mail(estimate, draft, confirm), with a sandbox - Sandbox — test keys (
sk_agent_test_), dry runs, lifecycle simulation, zero charges - Webhook notifications — HMAC-signed JSON payloads fire on every status transition
- MAILBOX.md standing instructions — configure rules for outbound mail and agent mailbox workflows
- Human-in-the-loop —
requires_approval=truepauses for human approval - Billing safeguards —
X-Max-Cost-Centsheader,dry_run=true, daily spend caps
A real street address + PMB for your agent at the staffed, USPS-compliant Manhattan Beach, CA facility, $20/mo. Mailboxes are live now: get one at signup or with POST /v1/mailing-address-requests. The PMB number is assigned after USPS Form 1583 verification. USPS Form 1583 ties a verified human to every agent mailbox: one online notary session, two IDs, fee waived.
- Arrives — staff log each letter and package with an envelope photo; webhooks
inbound.received,inbound.keywords_matchedandinbound.pages_ready - Reads —
GET /v1/inbound-items?q=searches senders, references and OCR text;GET /v1/inbound-items/{id}/pagesreturns OCR per page - Acts —
POST /v1/inbound-items/{id}/actionsproposesscan,forwardordiscard; the owner approves at the quoted price - Plan — $20/mo includes 30 pieces and 5 packages a month and two Open & scan requests;
GET /v1/inbound-planreturns every rate - Sandbox —
sk_agent_test_keys use the same routes on the account's sample letter, with nothing charged
No mailbox yet? Request a mailing address # with POST /v1/mailing-address-requests; the human finishes USPS Form 1583 online.
| Protocol | Endpoint | Details |
|---|---|---|
| REST API | https://mailbox.bot/api/v1 |
Outbound mail, agent mailbox reads and actions, and inbound forwarding context |
| MCP | https://mailbox.bot/api/mcp |
55 tools for outbound mail, agent mailbox search and actions, inbound context, facility messaging, webhooks, and sandbox lifecycle simulation |
| A2A | https://mailbox.bot/api/a2a |
10 skills for agent-to-agent task execution |
| OpenClaw | https://mailbox.bot/.well-known/agent.json |
Multi-protocol agent card |
| Plan | Price | Status | What you get |
|---|---|---|---|
| Inbound context + outbound mail | $0/mo | Live now | Private inbound forwarding alias included. Send outbound mail by dashboard, API, or MCP. |
| Agent mailbox | $20/mo | Live now | Street address + PMB at the Manhattan Beach, CA facility; 30 pieces and 5 packages a month included; scan, forward or discard with owner approval. |
Outbound pricing: a 1-page USPS First-Class letter starts at $3.00; printing is $0.40/page B&W or $0.70/page color total (including the $0.30/page color upgrade). Published USPS 1-page floors are Priority Mail $15.00, Certified Mail $20.00, and Certified + Electronic Return Receipt $24.00. FedEx 2Day takes a fixed $8.00 reduction and FedEx Overnight a fixed $18.00 adjustment after the carrier baseline. Outbound mail uses prepaid credits; use dry_run=true and cost_breakdown for the authoritative quote.
Full pricing: mailbox.bot/pricing
No SDK required — all integrations use the REST API via standard HTTP libraries.
- LangChain (Python)
- CrewAI (Python)
- LlamaIndex (Python)
- Vercel AI SDK (TypeScript)
- OpenAI Agents SDK (Python)
- Website
- API Docs
- Full API Reference (LLM-friendly)
- MCP Install Guide
- MCP Server Card
- Public MCP Tool Catalog
- Official MCP Registry Name —
bot.mailbox/mailbox - Sandbox & Test Keys
- OpenAPI Spec
- Agent Discovery
- Pricing
- Contact
npm install -g clawhub
clawhub login
clawhub publish . \
--slug mailbox-bot \
--name "mailbox.bot" \
--version 5.3.4 \
--changelog 'v5.3.4 — Agent mailbox rental is $20/mo for new renters (was $15/mo) from 20 Nov 2026; allowances, usage rates and outbound prices are unchanged'
clawhub inspect mailbox-botQuestions? mailbox.bot/contact