# Mailroom
> Corporate shipping API for AI agents: quote, buy, track, and void UPS/FedEx/USPS labels on behalf of an organization.

## Connect
- MCP endpoint (streamable HTTP, stateless): POST https://app.mailroom.software/mcp
- REST API: https://app.mailroom.software/api/v1 — OpenAPI at /.well-known/openapi.json
- Auth: API key (Authorization: Bearer mk_live_…, created by an org admin in Mailroom settings) or OAuth 2.1 (dynamic client registration at /oauth/register)
- Self-serve signup (no human needed to start): POST /api/v1/signups → org + mk_test_ key in one call
- Sandbox: mk_test_ keys run synthetic RIGHT HERE on production — no host change (see below)

## Sandbox
mk_test_ keys on production run in SYNTHETIC mode: quotes/labels/tracking/voids are simulated end-to-end (deterministic realistic rates, zero carrier calls, zero charges, labels not shippable). Responses carry "synthetic": true. IMPORTANT: sandbox prices are SIMULATED and do NOT reflect the rates you will get in production — they are plausible for integration testing only; never use them for cost estimates, price comparisons, or business decisions. Get real prices with a live key. Magic validation addresses: line1 containing AMBIGUOUS → candidate list; INVALID → rejection. mk_live_ keys always hit real carriers and are quota'd: self-serve keys start at 100 quotes/day (admin-issued keys may differ — GET /api/v1/usage shows YOUR key's live policy; raise via /api/v1/limits/requests).

## Flow
1. POST /api/v1/quotes (or MCP get_shipping_rates) — validates the address, returns quoteId + priced rates. No cost.
2. POST /api/v1/shipments (or MCP create_shipment) with quoteId + rateId + Idempotency-Key — buys a real label. May return pending_approval: a human manager approves in Slack.
3. GET /api/v1/shipments/:id — status, tracking events, label.
4. POST /api/v1/shipments/:id/void — void within the carrier window.

## Billing (prepaid balance)
Shipping on Mailroom's carrier accounts draws from a prepaid org balance. Errors with code insufficient_balance (HTTP 402) mean: fund first.
1. POST /api/v1/billing/setup-link → send the URL to your human admin (adds a card via Stripe, signs the billing authorization).
2. POST /api/v1/billing/top-up { amount_cents ≥ 5000 } with Idempotency-Key — funds the balance.
3. POST /api/v1/keys/activate-live → mk_live_ key once a card + authorization + positive balance are in place.
GET /api/v1/billing shows balance, refill settings, and unlock state.

## Docs
- /docs/agents — one-page integration guide
- /docs/api — human-readable API overview
- /legal/terms and /legal/privacy (mailroom.software) — legal terms; GET /api/v1/legal for current versions