# mailbox.bot Agent Quickstart

> A concise Markdown quickstart for autonomous agents and the humans managing them. Start here if you want the smallest, clearest path from discovery to first API call.

## What mailbox.bot does

- Give an agent a real US mailing address through a CMRA-backed virtual mailbox.
- Receive inbound postal mail and documents, then request scans, photos, holds, forwarding, shredding, or disposal.
- Send outbound letters, legal notices, certified mail, and batch mail through the API.
- Keep a human in the loop for approvals, payment, identity verification, and any rule that should pause before action.

## Public discovery endpoints

- [llms.txt](https://mailbox.bot/llms.txt): curated LLM overview
- [llms-full.txt](https://mailbox.bot/llms-full.txt): longer API reference
- [agents.txt](https://mailbox.bot/agents.txt): capability inventory
- [REST root](https://mailbox.bot/api/v1): API root discovery
- [OpenAPI JSON](https://mailbox.bot/api/openapi.json): machine-readable REST schema
- [OpenAPI YAML](https://mailbox.bot/openapi.yaml): alternate OpenAPI format
- [MCP endpoint](https://mailbox.bot/api/mcp): Model Context Protocol server
- [MCP tool catalog](https://mailbox.bot/api/mcp/tools): public MCP tool list
- [A2A endpoint](https://mailbox.bot/api/a2a): Agent-to-Agent endpoint
- [A2A agent card](https://mailbox.bot/.well-known/a2a-agent-card): well-known A2A discovery
- [OpenClaw agent card](https://mailbox.bot/.well-known/agent.json): multi-protocol discovery document
- [Human-readable API docs](https://mailbox.bot/api-docs): interactive docs
- [MCP install guide](https://mailbox.bot/mcp-install): integration guide for MCP clients

## If the human needs context first

- [Why agentic mail](https://mailbox.bot/why-agentic-mail): category framing and operator-level thesis
- [Workflow library](https://mailbox.bot/workflows): concrete vertical guides
- [Home services workflow](https://mailbox.bot/workflows/home-services): permit and property signals into personalized physical outreach
- [Real estate acquisitions workflow](https://mailbox.bot/workflows/real-estate-acquisitions): deal-triggered direct mail with workflow follow-up
- [Business mail workflow](https://mailbox.bot/workflows/business-mail): contracts, notices, invoices, and compliance mail
- [Outbound Mail API](https://mailbox.bot/outbound-mail-api): sending surface
- [Virtual Mailbox for Agents](https://mailbox.bot/virtual-mailbox-for-agents): inbound receiving surface

## Current self-serve plans

- Virtual Mailbox: $2/mo. Real CMRA address for inbound postal mail plus outbound access. Form 1583 and notary required.
- Outbound Only: $0/mo. No inbound address. Send physical mail via API with per-piece printing and postage charges.

See [pricing](https://mailbox.bot/pricing) for current details and higher-volume workflows.

## Recommended onboarding path

### 1. Optional: create a lead handle

Use the waitlist endpoint if you want a durable public status handle before creating the operator account.

```bash
curl -X POST https://mailbox.bot/api/v1/waitlist \
  -H "content-type: application/json" \
  -d '{
    "email": "agent@example.com",
    "needs": "receive legal notices and send certified responses",
    "callback_url": "https://agent.example.com/webhooks/mailbox-bot"
  }'
```

Persist the returned `lead_id`. It can be used later to check status and stitch the eventual account back to the same evaluation journey.

### 2. Create the operator account

```bash
curl -X POST https://mailbox.bot/api/v1/signup \
  -H "content-type: application/json" \
  -d '{
    "email": "operator@example.com",
    "password": "securepassword123",
    "full_name": "Jane Operator",
    "lead_id": "wl_example123456789"
  }'
```

### 3. Hand off to the human for the browser-only steps

The human operator must complete:

- Email verification
- Phone verification
- Payment method setup
- Form 1583 and notary, if using Virtual Mailbox
- Plan selection

### 4. Start authenticated API use

Once onboarding is complete, the operator can create an `sk_live_...` or `sk_agent_live_...` key.

```bash
curl https://mailbox.bot/api/v1/agents \
  -H "Authorization: Bearer sk_agent_live_..."
```

## Common first actions

### Send outbound mail

```bash
curl -X POST https://mailbox.bot/api/v1/mail \
  -H "Authorization: Bearer sk_agent_live_..." \
  -H "X-Mailbox-MD-Version: 1" \
  -F 'document=@notice.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'
```

### Read mailbox instructions

```bash
curl https://mailbox.bot/api/v1/agents/AGENT_ID/instructions \
  -H "Authorization: Bearer sk_agent_live_..."
```

### Explore available MCP tools

```bash
curl https://mailbox.bot/api/mcp/tools
```

## Operator guidance to surface in your own agent UI

- mailbox.bot is designed so agents can drive the flow, but identity and payment still require a real human.
- Treat `MAILBOX.md` as the operating contract. Fetch it on boot and respect the `X-Mailbox-MD-Version` header on mutating calls.
- Prefer webhook-driven automation after onboarding. Polling is useful during signup, but webhooks are better once the account is active.

## If you only remember three URLs

- [https://mailbox.bot/llms.txt](https://mailbox.bot/llms.txt)
- [https://mailbox.bot/api/openapi.json](https://mailbox.bot/api/openapi.json)
- [https://mailbox.bot/.well-known/agent.json](https://mailbox.bot/.well-known/agent.json)