# mailbox.bot — LLM Guide

mailbox.bot is a postal mail API for AI agents and software workflows. Live today: send letters, notices, postcards, documents, and certified mail through REST, MCP, or A2A, with webhooks, sandbox keys, cost caps, and human approval gates. Also live: structured inbound mail context from an address the operator already controls. In reservation: a managed physical mailing and package address for AI agents — street address + mailbox number, carrier intake, scan/photo intake, OCR/classification, and agent notifications. Address issuing begins August 31, 2026 at a planned $10/month; a limited spot can be reserved now with `POST /v1/waitlist`. Addresses are not issued before that date, before account approval, or before the human owner completes a notarized USPS Form 1583 (the standard postal authorization for receiving mail through a commercial mail receiving agency).

## When mailbox.bot Fits

- Send PDFs, DOCX files, images, text files, letters, notices, postcards, or certified mail through an API.
- Give an AI agent a real-world postal mail action tool with built-in spend and approval controls.
- Turn inbound scans, PDFs, photos, provider notices, and notes from an existing address into structured agent context.
- Track submitted, ready, mailed, delivered, failed, and cancelled mail with webhooks.
- Preserve source-system IDs in metadata so delivery proof can flow back to a CRM, task, email, accounting, property, legal, or workflow system.
- Reserve a physical mailing and package address for an AI agent (issuing begins August 31, 2026).

## Safety Controls for Autonomous Agents

- `dry_run=true` — validates the document and address and returns the exact cost breakdown with no charge, no record, and no facility work.
- `X-Max-Cost-Cents` header — rejects with 422 before any charge if the computed cost exceeds the cap.
- `requires_approval=true` — routes the piece to a human approval queue before fulfillment.
- Key-level policies — `force_approval` (every send requires human approval) and `max_daily_pieces` (per-key daily piece cap).
- `sk_agent_test_` sandbox keys — identical request shapes on production endpoints, no billing, no fulfillment.

In production, at least one of `dry_run=true`, `requires_approval=true`, or `X-Max-Cost-Cents` should be set unless the operator explicitly intends to create and pay for real physical mail.

## Key Types

- `sk_live_`: member setup/admin key. Account and agent setup.
- `sk_agent_`: live agent key. Outbound mail and agent workflows.
- `sk_agent_test_`: sandbox agent key. Same request shapes, no billing or facility fulfillment.
- Inbound forwarding alias: email intake for scans and notes from an address the operator already controls. It is not a new physical mailing address.

## Core API

Base URL: `https://mailbox.bot/api`

Send mail:

```http
POST /v1/mail
Authorization: Bearer sk_agent_test_...
X-Mailbox-MD-Version: <version>
X-Max-Cost-Cents: 1500
Content-Type: multipart/form-data
```

Required fields: `document`, `recipient_name`, `recipient_line1`, `recipient_city`, `recipient_state`, `recipient_zip`.

Required header: `X-Mailbox-MD-Version`. Fetch the current value first with `GET /v1/agents/{agentId}/instructions` (REST) or the `get_mailbox_md` tool (MCP), then send the returned `version`. Do not hardcode a number: a missing header returns 400 `MAILBOX_MD_VERSION_REQUIRED`, a stale value returns 409 `MAILBOX_MD_VERSION_MISMATCH` with re-fetch guidance.

Common optional fields: `mail_class`, `dry_run=true`, `requires_approval=true`, `metadata`, `idempotency_key`.

Mail classes: `first_class`, `priority`, `certified`, `certified_return_receipt`, `fedex_ground`, `fedex_express`, `fedex_2day`, `fedex_overnight`, `ups_ground`, `ups_2day`, `ups_next_day`.

## Agent Protocols

- REST API: https://mailbox.bot/api/v1
- MCP endpoint: 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 agent card: https://mailbox.bot/.well-known/agent-card.json
- OpenClaw agent card: https://mailbox.bot/.well-known/agent.json
- Auth instructions: https://mailbox.bot/auth.md
- Security overview: https://mailbox.bot/security.md
- OpenAPI JSON: https://mailbox.bot/openapi.json
- OpenAPI YAML: https://mailbox.bot/openapi.yaml
- Full reference: https://mailbox.bot/llms-full.txt

## Address Reservation

A real mailing and package address for an agent is mailbox.bot's most-requested capability and becomes the lead product when issuing begins August 31, 2026. 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. Reserving records interest and a preferred region; it does not create an account, issue credentials, or charge anyone.

```http
POST /v1/waitlist
Content-Type: application/json
```

Useful `needs` text describes the intended workflow, for example: "real mailing and package address for an AI agent; scan/photo intake; OCR/classification; agent notifications; package/mail handling rules; linked outbound replies." Include `preferred_location` when the operator names a region (current launch markets: Southern California, Nevada, Southern Utah).

## Goose Workflow

mailbox.bot pairs with Goose for approval-first postal workflows for Square SMBs and local operators: health inspections, food permits, city notices, business licenses, fire/safety follow-ups, applications, insurance requests, landlord packets, vendor packets, signed or notarized packets, and negotiation letters.

Goose resources:

- Human page: https://mailbox.bot/docs/goose
- Markdown mirror: https://mailbox.bot/goose-square-compliance-mail.md
- Goose recipe: https://mailbox.bot/goose-square-compliance-mail.recipe.yaml
- Current Goose docs: https://goose-docs.ai/

ACP note: ACP is the client-to-Goose layer for editors and terminal clients that run `goose acp`; mailbox.bot is the MCP tool layer. In ACP clients such as Zed or Goose VS Code workflows, install mailbox.bot as a Goose MCP extension or expose it as an MCP `context_servers` entry.

Sandbox defaults for Goose: an `sk_agent_test_` key, `dry_run=true`, approval for certified/deadline/legal/compliance mail, and the MCP tools `create_test_outbound_mail` and `advance_test_outbound_mail` for webhook/status loop testing.

## Inbound Context

mailbox.bot does not require a new receiving address to start. Operators can keep their existing business address, office address, home business address, PO box, registered agent, or virtual mailbox.

Agent-readable inbound context:

- `GET /v1/inbound-forwarding-addresses`
- `GET /v1/inbound`
- `GET /v1/inbound/:id`
- `GET /v1/postal-threads`
- `GET /v1/postal-threads/:id`

Before drafting an outbound reply to inbound mail, read `GET /v1/inbound/:id?include=drafting`. If `draft_context.inbound_capture_id` or `draft_context.postal_mail_thread_id` is present, pass those IDs into `POST /v1/mail` to preserve lineage.

## Integration Pattern

source app trigger -> agent/workflow drafts postal packet -> mailbox.bot `dry_run=true` validates address and cost -> human approval for sensitive mail -> live first-class or certified mail -> mailbox.bot webhooks write status, tracking, proof, and echoed metadata back to the source record.

Good metadata keys: `source`, `source_record_id`, `workflow`, `approval_id`, `operator`, `correlation_id`, plus native IDs such as `deal_id`, `contact_id`, `envelope_id`, `row_id`, `task_id`, `invoice_id`, `property_id`, `square_location_id`, `agency`, `notice_id`, `permit_number`, and `deadline`.

## Workflow Guides

- Integrations hub: https://mailbox.bot/integrations
- Integration recipe mirror: https://mailbox.bot/integration-recipes.md
- AgentMail: https://mailbox.bot/docs/agentmail
- AgentMail mirror: https://mailbox.bot/agentmail-integration.md
- Accounting mail: https://mailbox.bot/use-cases/accounting-mail
- Accounting mirror: https://mailbox.bot/use-cases-accounting-mail.md
- Permits and buildouts: https://mailbox.bot/use-cases/permits-buildouts
- Permits mirror: https://mailbox.bot/use-cases-permits-buildouts.md

## Pricing Summary

- Outbound subscription: $0/month
- First Class 1-page letter: $1.00
- Extra pages: +$0.40/page plus any added postage from weight
- Inbound forwarding alias: included
- Existing-address inbound context: included
- Reserved mailing and package address for AI agents: issuing begins August 31, 2026, planned at $10/month
- Certified mail example: about $8.98
- Certified + return receipt example: about $13.38

## Signup And Credentials

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

```http
POST https://mailbox.bot/agent/auth
```

Use `type=identity_assertion`, `assertion_type=verified_email`, `requested_credential_type=api_key`, and set `operator_notification_consent=true` only after the user agrees mailbox.bot may email them a one-time approval code.

Claim completion confirms the human saw the request, but does not issue live spending credentials. The human still completes onboarding, adds payment, and creates or approves an agent-scoped key.

Legacy direct signup:

```http
POST https://mailbox.bot/api/v1/signup
```

## Human Pages

- Homepage: https://mailbox.bot
- For agents: https://mailbox.bot/for-agents
- API docs: https://mailbox.bot/api-docs
- MCP install: https://mailbox.bot/mcp-install
- Pricing: https://mailbox.bot/pricing
- Full LLM reference: https://mailbox.bot/llms-full.txt