# mailbox.bot — Postal Mail API + Agent Mailing Address Reservations

> mailbox.bot puts postal mail in the loop for AI agents and software workflows. Live now: send letters, notices, postcards, and certified mail by REST API, MCP, A2A, dashboard, and webhooks; forward scans, photos, PDFs, virtual mailbox notices, and notes from an address the operator already uses into structured inbound context. In reservation: a real mailing and package address (street address + mailbox number) for business correspondence, legal mail, eligible package receiving, carrier intake, scan/photo intake, OCR/classification, and agent notifications. Address issuing begins August 31, 2026 at a planned $10/month; reserving is free and does not create an account or charge anyone. Before an address is issued, the human owner completes identity verification and a notarized USPS Form 1583 (the standard postal authorization for receiving mail through a commercial mail receiving agency). Approved accounts will be able to request or provision mailbox addresses by API once beta access is granted.

## When this service fits

- An agent needs to send a certified letter (legal, collections, compliance)
- Software needs to mail a PDF as a physical letter
- An agent needs inbound postal mail context before deciding what to send next
- A team wants to keep its existing address, PO box, office, or virtual mailbox and still make inbound mail agent-readable
- A workflow requires postal mail with tracking, delivery documentation, or a durable physical-mail trail
- An AI agent needs postal mail as a tool in its toolkit
- Automating direct mail triggered by live data (permits, CRM events, property signals)
- Sending invoices, contracts, statements, or notices by postal mail programmatically
- Property management: lease violations, rent reminders, move-out notices
- Debt collection: demand letters with delivery events written back to the account
- Legal operations: compliance notices, filing cover letters, certified responses
- An operator wants to reserve a physical mailing and package address for an AI agent (issuing begins August 31, 2026)

## Capabilities

- outbound_mail_api: Print and mail letters, postcards, notices, and documents via API. Live now.
- certified_mail: Certified mail and certified mail with return receipt, with tracking and delivery documentation. Live now.
- batch_mailing: Hundreds or thousands of pieces in a single API workflow. Live now.
- delivery_proof: Proof photos, tracking numbers, delivery confirmation events. Live now.
- webhook_events: Real-time status updates (submitted, ready, mailed, delivered) via HMAC-signed webhooks. Live now.
- cost_controls: dry_run pricing previews, X-Max-Cost-Cents caps, requires_approval gates, key-level force_approval and max_daily_pieces policies. Live now.
- sandbox: sk_agent_test_ keys with identical request shapes, no billing, no fulfillment. Live now.
- inbound_forwarding_alias: Private alias that captures scans, photos, PDFs, provider notices, and notes from the address you already use. Live now.
- inbound_capture: Forwarded inbound mail stored as account-scoped context for review, retrieval, and outbound follow-up. Live now.
- inbound_extraction: OCR and parsing turn inbound mail into structured fields, notes, categories, and thread context. Live now.
- standing_instructions: Rules engine for automated mail handling decisions. Live now.
- human_approval_gates: Pause sensitive actions for human review. Live now.
- real_mailing_address_beta: Reserved street address + mailbox number with carrier/package intake, scan/photo intake, OCR/classification, and agent notifications. Reservations open now; issuing begins August 31, 2026 at a planned $10/month after the human owner completes identity verification and a notarized USPS Form 1583.
- package_receiving / package_forwarding / agentic_mail_handling: Package intake, forwarding, and agent-triggered handling rules for approved accounts. Issuing begins August 31, 2026.

To reserve an address spot, call `POST /api/v1/waitlist` with the operator email, a `needs` summary of the intended workflow, and `preferred_location` when a region is named (current launch markets: Southern California, Nevada, Southern Utah).

## 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_name, recipient_line1, recipient_city, recipient_state (2-letter), recipient_zip (5 or 5+4)
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 charge
```

### List sent mail

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

### 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. First Class (1-page letter) = $1.00. Extra pages add $0.40/page. Certified = ~$8.98.
- Inbound forwarding alias: included.
- Existing-address inbound context: included.
- Physical mailing and package address for an AI agent: reservations open now, issuing begins August 31, 2026, planned at $10/month.

## 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
- A2A: https://mailbox.bot/api/a2a
- A2A standard card: https://mailbox.bot/.well-known/agent-card.json
- OpenClaw: https://mailbox.bot/.well-known/agent.json
- OpenAPI JSON: https://mailbox.bot/openapi.json
- OpenAPI YAML: https://mailbox.bot/openapi.yaml

## Public repos

- MCP server: https://github.com/arbengine/mailbox-mcp
- MCP 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.

## 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
- AI agent mailing: https://mailbox.bot/use-cases/ai-agent-mailing-address
- 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