# mailbox.bot — Postal Mail API for AI Agents

mailbox.bot sends outbound postal mail through REST or MCP and turns forwarded scans, photos, PDFs, notices, and notes from an address the operator already controls into digital/OCR context; both are live now. Mailbox.bot-issued physical receiving addresses and associated package receiving are **Not live yet · Launch ETA: mid/late September.** Reservations are open, but a reservation does not issue an address or PMB and does not activate physical custody. After launch, approved receiving accounts with an assigned PMB will use the live-credential-only, REST-only `/v1/inbound-items*` contract. `/v1/mailboxes` creates logical outbound endpoints and never issues a receiving PMB.

## When this service fits

- Send outbound letters, notices, postcards, certified mail, and document packets with cost caps, approval gates, tracking, proof, and webhooks.
- Read forwarded digital/OCR inbound context and preserve lineage into outbound replies.
- After launch, approval, and PMB assignment, read letters, flats, and parcels at the assigned PMB and request Open & Scan.

## Physical inbound boundary

- Status: **Not live yet · Launch ETA: mid/late September.** Reserving managed-address access records interest only; it does not provision or activate physical receiving.
- Canonical member routes: `GET /v1/inbound-items`, `GET /v1/inbound-items/:id`, `POST /v1/inbound-items/:id/actions`, and `GET /v1/inbound-items/:id/scans`.
- After launch and assignment, only `open_and_scan` is callable. Do not infer forwarding, discard, shred, rules, expected shipments, notes, tags, or other actions.
- Physical custody is not exposed through MCP and cannot be tested with `sk_agent_test_`. Facility operations are defined under `Physical Inbound — Facility` in OpenAPI.

## API quick reference

### Send a letter

```
POST /api/v1/mail
Authorization: Bearer sk_agent_...
X-Mailbox-MD-Version: <version>
Content-Type: multipart/form-data

Required fields: document (PDF file), recipient_line1, recipient_city, recipient_state (2-letter), recipient_zip (5 or 5+4), plus at least one of recipient_name or recipient_company.
recipient_company adds a company or organization line between recipient_name and recipient_line1 when both are present; company-only mail is also valid.
Required header: X-Mailbox-MD-Version — fetch the current value with GET /api/v1/agents/{agentId}/instructions and send the returned version. Missing → 400, stale → 409.
Optional: mail_class (defaults to first_class), dry_run=true for validation + exact cost preview without spending credits
```

Credit/chat UX: Agents can read prepaid balance with REST `GET /api/v1/credits`; Cursor/MCP agents use `get_usage` for "How many credits do I have left?" Answer with the balance display and tell the human only they can add funds or change Auto-Fill in dashboard billing. Agents never access Stripe or card data; eligible live orders may trigger bounded server-managed Auto-Fill only after human opt-in. Business REST agents may explicitly group related orders with `POST /api/v1/mail-runs`, child `mail_run_id` values, and one commit; the close is a fixed five minutes, not inferred timing. For "cancel this order," call REST `DELETE /api/v1/mail/{id}` or MCP `cancel_outbound_mail` while the order is still submitted, then report cancellation status, returned credits, updated balance, and whether it was already cancelled.

### List sent mail

```
GET /api/v1/mail
Authorization: Bearer sk_agent_...
```

### Retrieve outbound source document

```
GET /api/v1/mail/{id}/document
Authorization: Bearer sk_agent_... with document.read
```

Encrypted source documents are decrypted through mailbox.bot. Do not expect direct Supabase Storage URLs for encrypted rows.

### List inbound mail context

```
GET /api/v1/inbound
Authorization: Bearer sk_agent_...
```

### MCP integration

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

## Pricing

- Outbound: $0/mo. Printing is $0.40/page B&W or $0.70/page color total (including the +$0.30/page color upgrade). Formula: configured handling + selected printing + carrier postage estimate/rate; FedEx and UPS estimates are base estimates by origin and destination zone/region, with source details in `cost_breakdown`; FedEx Overnight adds a fixed $18.00 after the otherwise-calculated baseline (`service_adjustment_cents: 1800`). USPS First-Class Mail has a $2.00 published one-page baseline (extra pages add configured per-page printing plus added postage). Dashboard service cards, dry runs, sandbox estimates, and `cost_breakdown` are authoritative for account-specific pricing.
- Email forwarding intake and existing-address inbound context: included.

## Protocols

- auth.md agent registration: https://mailbox.bot/auth.md
- Security overview: https://mailbox.bot/security.md
- OAuth protected resource metadata: https://mailbox.bot/.well-known/oauth-protected-resource
- OAuth authorization server metadata: https://mailbox.bot/.well-known/oauth-authorization-server
- REST API: https://mailbox.bot/api/v1
- MCP: https://mailbox.bot/api/mcp
- MCP tool catalog (public, no auth): https://mailbox.bot/api/mcp/tools-public
- OpenClaw: https://mailbox.bot/.well-known/agent.json
- OpenAPI JSON: https://mailbox.bot/openapi.json
- OpenAPI YAML: https://mailbox.bot/openapi.yaml

## Public repos

- Hosted MCP app and install surface: https://github.com/arbengine/mailbox
- Agent instruction skill: https://github.com/arbengine/mailbox-bot-skill

## Framework integrations

No SDK required — plain REST calls work from any framework:

- Integration recipes hub: https://mailbox.bot/integrations
- Integration recipes markdown: https://mailbox.bot/integration-recipes.md
- LangChain (Python): https://mailbox.bot/docs/langchain
- CrewAI (Python): https://mailbox.bot/docs/crewai
- LlamaIndex (Python): https://mailbox.bot/docs/llamaindex
- Vercel AI SDK (TypeScript): https://mailbox.bot/docs/vercel-ai-sdk
- OpenAI Agents SDK (Python): https://mailbox.bot/docs/openai-agents-sdk
- MCP (any): https://mailbox.bot/mcp-install

## Agent signup and auth discovery

The guarded auth.md flow replaces pasted API keys with an email approval ceremony — the human consents, receives a one-time code, and reads it back:

POST https://mailbox.bot/agent/auth
Content-Type: application/json
No auth required. Rate limited per IP and per target email.

Required shape: type=identity_assertion, assertion_type=verified_email, assertion=<operator email>, requested_credential_type=api_key, operator_notification_consent=true.

The user must consent before the agent shares their email. mailbox.bot emails the operator a one-time approval code and returns claim_token + claim_complete_url to the agent. The agent asks the user to read back the 6-digit code, then posts claim_token + otp to /agent/auth/claim/complete.

This proves the human saw the request. It does not issue live spending credentials. The human still completes onboarding, adds payment, and creates or approves an agent-scoped API key. Sandbox keys (sk_agent_test_) work first; live mail supports X-Max-Cost-Cents, force_approval, max_daily_pieces, and requires_approval.

Legacy direct account signup is also available:

POST https://mailbox.bot/api/v1/signup
Content-Type: application/json
No auth required. No CAPTCHA. No TOS checkbox.

Fields: full_name (string), email (string), password (string, min 8 chars)

After signup, the human operator verifies email and completes KYC (~5 min). The agent then gets API keys from the dashboard.

## FAQ

- AI agent mailing address FAQ on the homepage: https://mailbox.bot/#faq

## Use case guides

- Certified mail API: https://mailbox.bot/use-cases/certified-mail-api
- Debt collection mail: https://mailbox.bot/use-cases/debt-collection-mail
- Legal notice automation: https://mailbox.bot/use-cases/legal-notice-automation
- Property management notices: https://mailbox.bot/use-cases/property-management-notices
- Accounting mail workflows: https://mailbox.bot/use-cases/accounting-mail
- Permit and buildout mail workflows: https://mailbox.bot/use-cases/permits-buildouts
- Asset acquisition offers: https://mailbox.bot/use-cases/asset-acquisition-offers
- Postcard campaigns: https://mailbox.bot/use-cases/postcard-campaigns
- Insurance dispute mail: https://mailbox.bot/use-cases/insurance-dispute-mail
- LLC formation filings: https://mailbox.bot/use-cases/llc-formation-mail
- Government filings: https://mailbox.bot/use-cases/government-filings

## Workflow guides

- Home services prospecting: https://mailbox.bot/workflows/home-services
- Real estate acquisitions: https://mailbox.bot/workflows/real-estate-acquisitions
- Business mail automation: https://mailbox.bot/workflows/business-mail

## Human context pages

- Homepage: https://mailbox.bot
- Why agentic mail: https://mailbox.bot/why-agentic-mail
- Pricing: https://mailbox.bot/pricing
- For agents: https://mailbox.bot/for-agents

## Markdown mirrors (for LLM retrieval)

- Agent quickstart: https://mailbox.bot/agent-quickstart.md
- Why agentic mail: https://mailbox.bot/why-agentic-mail.md
- Outbound mail API: https://mailbox.bot/outbound-mail-api.md
- Virtual mailbox: https://mailbox.bot/virtual-mailbox-for-agents.md
- Workflow guides: https://mailbox.bot/workflows.md

## Full API reference

- https://mailbox.bot/llms-full.txt