# mailbox.bot

> Software infrastructure for managed micro-fulfillment. Connects people, businesses, and AI agents with independently licensed facility operators — including CMRA mail centers and warehouse operators — for package and mail receiving, storage, and forwarding. Provision reference codes, receive packages, and manage logistics via dashboard or API.

## What you can do here

- Provision a physical shipping address in ~3 seconds via API
- Receive packages from FedEx, UPS, DHL, Amazon, OnTrac, LaserShip, and other private carriers
- Get instant HMAC-signed webhook notifications with photos, tracking, weight, and dimensions
- Request actions on packages: scan, photograph, video, forward, shred, dispose, hold, return to sender
- Set standing instructions that auto-trigger actions based on carrier, weight, sender, or tracking patterns
- Pre-register expected shipments for automatic matching and processing on arrival
- Tag and annotate packages for persistent agent memory across the package lifecycle
- Fetch standing instructions (MAILBOX.md) — renter's handling rules, forwarding preferences, auto-shred criteria
- Inspect webhook delivery history — debug failed deliveries, view attempt details and payloads

## Quick start

Agents can initiate signup and fill onboarding data programmatically. Identity verification and payment require a human, but your agent can drive the entire process — create the account, fill forms, and hand off to the human operator for the steps that need a real person. After onboarding, the agent manages the mailbox autonomously.

This is the recommended pattern for DAOs, businesses, and individuals who want an AI agent to manage their physical mail and packages.

### Step 1: Agent creates the account

```
POST https://mailbox.bot/api/v1/signup
Content-Type: application/json

{
  "email": "operator@yourdao.xyz",
  "password": "securepassword123",
  "full_name": "Jane Smith",
  "needs": "sensor kits + prototype PCBs, ~20 pkgs/month"
}
```

Required fields: email (valid format), password (min 8 chars), full_name (2-100 chars)
Optional fields: needs (free text describing use case)

Response (201):
```json
{
  "success": true,
  "message": "Account created. A verification email has been sent. The operator must verify their email and complete KYC to activate the account.",
  "next_steps": {
    "verify_email": "Click the verification link sent to the operator's email",
    "complete_kyc": "https://mailbox.bot/staging",
    "after_kyc": "Select a plan, add payment, and create your first agent to get API keys"
  }
}
```

No captcha required. Rate limited to 5 requests per minute per IP. A verification email is sent automatically — the human operator must click it to proceed.

### Step 2: Agent fills onboarding data (optional)

After the human verifies their email and logs in, the agent can pre-fill onboarding steps via API if it has session credentials:

- **Service type**: `POST /api/onboarding/select-service` — `{ "service_type": "virtual_mailbox" }` or `"warehouse"`
- **Form 1583 address** (virtual mailbox only): `POST /api/onboarding/form1583/save-details` — home address + use type (personal/business)
- **TOS acceptance**: `POST /api/onboarding/tos`

Or the human can complete these steps in the browser at https://mailbox.bot/staging — they take ~2 minutes.

### Step 3: Human completes identity + payment (one-time)

These steps require a real person in a browser. The agent cannot complete them:

- **Payment method** — Stripe card entry (no prepaid/gift cards)
- **KYC** — Stripe Identity verification (selfie + government ID) — warehouse only
- **Form 1583 notarization** — Remote notary session via OneNotary ($25, ~5 min video call with government ID) — virtual mailbox only
- **Plan selection + payment** — Stripe Checkout

For virtual mailbox: after notarization, the facility reviews the Form 1583 (1-2 business days). Once approved, the account auto-provisions.

For warehouse: after KYC, the account provisions immediately.

### Step 4: Agent takes over

Once onboarding completes, an agent and mailbox are auto-created. The agent now has:

- A **physical mailing address** (e.g., `1234 Logistics Pkwy, Suite 7F3A, City, ST 00000`)
- **API keys** (`sk_live_` for account, `sk_agent_live_` for agent-scoped)
- **Webhook notifications** for every package event
- Full API/MCP/A2A access to manage packages, request actions, set rules, and more

```
GET https://mailbox.bot/api/v1/agents
Authorization: Bearer sk_live_xxxxxxxxxxxxx
```

Response:
```json
{
  "agents": [{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "procurement-bot",
    "slug": "procurement-bot",
    "endpoint": "procurement-bot.mailbox.bot",
    "mailbox": {
      "id": "MB-7F3A",
      "reference_code": "7F3A",
      "facility_address": "1234 Logistics Pkwy, Suite 7F3A, City, ST 00000"
    },
    "webhook_signing_key": "whsk_xxxxxxxxxxxxx",
    "status": "active"
  }]
}
```

Additional addresses: `POST /v1/mailboxes` with your agent_id.

### Use cases for agent-assisted onboarding

- **DAOs**: Agent signs up on behalf of a DAO treasury, human member completes KYC once, agent manages all physical mail for the organization
- **Businesses**: Agent provisions mailbox addresses for each department or project, human founder verifies once
- **Personal**: AI assistant signs up for its human, handles package logistics autonomously after one-time verification
- **Multi-agent**: One human verification unlocks multiple agent-managed mailboxes across facilities

## Service types

Your service type determines the facility you're provisioned at, the carriers accepted, and the verification requirements.

### Virtual Mailbox
- Provisioned at a CMRA-registered facility on our network
- Accepts USPS postal mail and documents only — packages are NOT accepted on this plan
- Do not ship packages to a virtual mailbox address; packages may be refused or returned to sender
- Requires KYC + USPS Form 1583 + notary session (in-person or remote)

### Warehouse Space
- Provisioned at a warehouse or fulfillment facility on our network
- Accepts packages from private carriers (FedEx, UPS, DHL, Amazon, etc.)
- Requires KYC only

Both include: intake documentation, package photography, webhook notifications, dashboard management, API access, agent protocol support, scan/forward/discard/return actions.

## How this differs from traditional 3PLs

- **Agent-native**: every interaction is API-first — no portals, no emails, no phone calls
- **No minimums, no contracts**: provision and deprovision addresses on demand
- **Per-action billing**: only pay for what your agent uses (scan $3, photo $1.50, forward $5+$2/lb)
- **Webhook-first**: structured JSON payloads fire the second a package arrives — not batch emails
- **Multi-protocol**: MCP (15 tools), A2A (v0.3), OpenClaw, REST — pick your protocol
- **Custodial model**: your property, facility custody — same legal framework as any warehouse or fulfillment center
- **Sub-second provisioning**: new addresses are usable for shipping within seconds of API call

## Coverage areas

- Southern California (active)
- Southern Nevada / Las Vegas (expanding)
- Utah (expanding)

## Capabilities

### Package receiving
- Carriers accepted depend on facility type (see Service types above)
- Private carriers: FedEx, UPS, DHL, Amazon, OnTrac, LaserShip, GSO, Spee-Dee
- CMRA facilities also accept USPS mail
- Automatic carrier detection from tracking number
- Photo documentation of every package on arrival (exterior, label, barcode)
- Weight and dimensions capture
- Expected shipment pre-registration with auto-matching

### Actions (request via API)
- **scan** — document scanning with OCR extraction ($3.00)
- **open_and_scan** — open package + scan internal contents ($5.00)
- **photograph** — photo documentation ($1.50)
- **record_video** — video recording of package handling ($5.00)
- **forward** — ship to another address ($5.00 base + $2.00/lb)
- **shred** — destroy contents ($2.00)
- **dispose** — discard package ($1.00)
- **return_to_sender** — return to carrier ($5.00)
- **hold** — pause for review or pickup (free)

Agent-friendly field aliases: the actions endpoint accepts both `"action"` and `"action_type"` (case-insensitive). Notes accepts `"note"`, `"text"`, or `"message"`. Tags accepts `"tag"`, `"label"`, or `"name"`.

### Automation
- Agent rules engine — auto-trigger actions based on carrier, weight, tracking patterns, sender
- Webhook notifications (HMAC-signed JSON) for package arrival, action completion, status changes
- Expected shipment matching — pre-register tracking numbers for automatic processing

### Agent memory
- Tag packages with labels for categorization
- Add observation notes with structured metadata
- Persistent context across the full package lifecycle

## Pricing

| Plan | Type | Price | Includes |
|------|------|-------|----------|
| Virtual Mailbox | CMRA | $10/mo | 10 pieces of postal mail/mo, USPS + all carriers, scan on arrival, 14-day storage, Form 1583 required |
| Business | Warehouse | $35/mo | 20 packages/mo, up to 50 lbs, scan/forward/discard, 30-day storage, private carriers |
| Business+ | Warehouse | $149/mo | ~100 sq ft space, 50 packages/mo, reorder/consolidation, 60-day storage |
| Enterprise | Warehouse | Custom | Unlimited packages, custom rules, SLA, reserved facility space |

Actions billed per use (see prices above). Full pricing: https://mailbox.bot/pricing

## Outbound mail

Agents can send physical mail via API. Submit a pre-rendered PDF and we print, stuff, stamp, and mail it. WYSIWYG — the facility prints exactly what you upload.

- `POST /api/v1/mail` — submit PDF with recipient address and mail class
- `GET /api/v1/mail` — list outbound mail (filter by status)
- `GET /api/v1/mail/:id` — get details with signed PDF URL
- `DELETE /api/v1/mail/:id` — cancel (only while still in submitted status)

Mail classes: first_class ($1.50), priority ($3.50), certified ($6.00), certified_return_receipt ($8.00). Color +$0.25/page, duplex +$0.50.

Status lifecycle: submitted → printing → mailed → delivered (or failed/cancelled). Webhook events fire at each transition. Requires `X-Mailbox-MD-Version` header (version contract). See llms-full.txt for complete docs.

## Protocols

- **REST API** (v1) — full API for agents, mailboxes, packages, actions, forwarding, scanning, tags, notes, rules, expected shipments, outbound mail, webhooks
- **MCP** (Model Context Protocol, spec 2025-11-25) — 18 tools for LLM integration: get_mailbox, list_packages, get_package, get_package_photos, request_action, request_scan, get_scan_results, add_tag, add_note, create_rule, register_expected, get_usage, update_webhook, send_outbound_mail, list_outbound_mail, get_outbound_mail, and more
- **A2A** (Agent-to-Agent Protocol, v0.3) — 9 skills including provision-address, receive-packages, package-forwarding, document-scanning, package-actions, standing-instructions, expected-shipment-matching, agent-memory, webhook-notifications
- **OpenClaw** — multi-protocol agent card at /.well-known/agent.json

## API authentication

Bearer token authentication. Three key types:
- **Member keys** (`sk_live_`) — full account access, all scopes, spans all agents. Use `?agent_id=` to scope agent-specific queries.
- **Agent keys** (`sk_agent_`) — scoped to a single agent. Queries auto-filter — no `agent_id` parameter needed.
- **Facility keys** (`sk_facility_`) — scoped to a facility for external scanner apps.

Scopes: agent.read, agent.write, package.read, package.write, mailbox.read, mailbox.write, webhook.manage, webhook.read, billing.read, message.send

Auth errors include a machine-readable `reason` field (e.g. `key_revoked`, `member_suspended`, `insufficient_scope`). See llms-full.txt for all 9 reason codes.

Rate limit: 100 requests/minute per API key.

## Just exploring?

Agents can join the waitlist without creating an account:

```
POST https://mailbox.bot/api/v1/waitlist
Content-Type: application/json

{
  "email": "agent@yourco.com",
  "needs": "sensor kits + prototype PCBs, ~20 pkgs/month, need SoCal address"
}
```

No captcha required. Rate limit: 5 requests per minute. We'll reach out when capacity opens in your region.

## Links

- Website: https://mailbox.bot
- Full API reference: https://mailbox.bot/llms-full.txt
- Pricing: https://mailbox.bot/pricing
- API docs: https://mailbox.bot/api-docs
- Agent card (OpenClaw): https://mailbox.bot/.well-known/agent.json
- A2A agent card: https://mailbox.bot/api/a2a/agent-card
- MCP tools: https://mailbox.bot/api/mcp/tools
- Waitlist: https://mailbox.bot/api/v1/waitlist
- Privacy: https://mailbox.bot/privacy
- Terms: https://mailbox.bot/terms