# mailbox.bot — Agent Quickstart

Agent mailboxes are live now: $15/mo for a street address + PMB at the Manhattan Beach, CA facility. Outbound mail still uses prepaid credits.

> Send postal mail from code in under 5 minutes. One API call: PDF + address = printed, stamped, mailed letter with photo proof and carrier tracking when the selected service includes tracking.

## Agent auth discovery

Agents without a key start here:

- Auth instructions: https://mailbox.bot/auth.md
- Protected resource metadata: https://mailbox.bot/.well-known/oauth-protected-resource
- Authorization server metadata: https://mailbox.bot/.well-known/oauth-authorization-server

`POST https://mailbox.bot/agent/auth` supports a guarded `verified_email` signup intent. It returns a `claim_token`, `claim_complete_url`, `relay_message`, `human_action_required` checklist, `lead_id`, `status_url`, `operator_notification`, and `callback_delivery`, but it does not issue live spending credentials. Set `operator_notification_consent: true` only after the user agrees mailbox.bot may email them a one-time approval code. Submit that code to `/agent/auth/claim/complete` to prove the human saw the request. The human operator must still complete onboarding, fund mailbox.bot credits, and approve an agent API key before live mail can be sent.

For live orders, use `X-Max-Cost-Cents`, prefer `force_approval` and `max_daily_pieces` on the key, and use `sk_agent_test_...` first whenever possible. MCP is optional: agents with only an API key and `/api-docs` can read prepaid balance with `GET /api/v1/credits`, while Cursor/MCP agents can use `get_usage` for "How many credits do I have left?" Only the signed-in human can add funds or change Auto-Fill; agents never access Stripe or card data. Eligible agent orders may trigger bounded server-managed Auto-Fill only after the human separately enables it. If a live send returns 409 for duplicate protection, inspect the existing `outbound_mail_id`; do not retry or change carrier to force a second funded mailpiece. To cancel a queued submitted order, call `DELETE /api/v1/mail/{id}` or MCP `cancel_outbound_mail`, then report returned credits and updated balance. Business REST agents can intentionally group related orders with `POST /api/v1/mail-runs`, child `mail_run_id` values, and an explicit commit; poll the fixed five-minute run rather than inferring a batch from timing.

## Send your first letter (30 seconds after you have an API key)

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

The `X-Mailbox-MD-Version` header is required on every send. Fetch the current value with `GET /api/v1/agents/{agentId}/instructions` (or the `get_mailbox_md` MCP tool) and send the returned `version` — do not hardcode it. Missing returns 400 `MAILBOX_MD_VERSION_REQUIRED`; stale returns 409 `MAILBOX_MD_VERSION_MISMATCH`.

That's it. mailbox.bot prints the PDF, stuffs an envelope, applies postage, and mails it. You get webhook events, photo proof, and a tracking number when the selected service includes carrier tracking. USPS First-Class Mail letters do not include carrier tracking by default.

To track status, configure a webhook for automatic `mail.ready`, `mail.mailed`, `mail.delivered`, and `mail.failed` events, or poll `GET /api/v1/mail/:id`. Webhook payloads include `callback_url` for the same canonical detail record with fresh signed document/photo URLs.

## Send certified mail (proof of mailing and delivery)

```bash
curl -X POST https://mailbox.bot/api/v1/mail \
  -H "Authorization: Bearer sk_agent_..." \
  -H "X-Mailbox-MD-Version: <version>" \
  -F 'document=@proof-packet.pdf' \
  -F 'recipient_name=John Doe' \
  -F 'recipient_line1=456 Oak Ave' \
  -F 'recipient_city=Chicago' \
  -F 'recipient_state=IL' \
  -F 'recipient_zip=60601' \
  -F 'mail_class=certified'
```

## Python

```python
import requests

resp = requests.post(
    "https://mailbox.bot/api/v1/mail",
    headers={
        "Authorization": "Bearer sk_agent_...",
        "X-Mailbox-MD-Version": current_version,  # from GET /v1/agents/{id}/instructions
    },
    files={"document": open("notice.pdf", "rb")},
    data={
        "recipient_name": "Jane Smith",
        "recipient_line1": "789 Elm St",
        "recipient_city": "Austin",
        "recipient_state": "TX",
        "recipient_zip": "78701",
        "mail_class": "certified",
    },
)
mail = resp.json()["outbound_mail"]
print(f"Sent: {mail['id']} — {mail['cost_display']}")
```

## JavaScript / Node.js

```javascript
const form = new FormData();
form.append("document", fs.createReadStream("invoice.pdf"));
form.append("recipient_name", "Acme Corp");
form.append("recipient_line1", "123 Main St");
form.append("recipient_city", "Los Angeles");
form.append("recipient_state", "CA");
form.append("recipient_zip", "90001");
form.append("mail_class", "first_class");

const res = await fetch("https://mailbox.bot/api/v1/mail", {
  method: "POST",
  headers: { Authorization: "Bearer sk_agent_...", "X-Mailbox-MD-Version": currentVersion }, // from GET /v1/agents/{id}/instructions
  body: form,
});
const { outbound_mail } = await res.json();
console.log(`Sent: ${outbound_mail.id}`);
```

## Add to any MCP agent (2 lines)

```json
{
  "mcpServers": {
    "mailbox-bot": {
      "url": "https://mailbox.bot/api/mcp",
      "headers": { "Authorization": "Bearer sk_agent_..." }
    }
  }
}
```

Your agent can now send postal mail using the `send_outbound_mail` MCP tool.

Read inbound mail with `get_mailbox_md` → `search_inbound_items` → `get_inbound_item` → `get_inbound_pages`, then propose scan, forward or discard with `request_inbound_action` for the owner to approve. Search sender, reference and OCR keywords, then cite the returned pages. A Sandbox key finds the account's Mojave Land Partners sample with `q` "Mojave". The older `get_agent_inbox_context` / `get_agent_inbox_sources` tools are deprecated but still served ([reference](https://mailbox.bot/api-docs#agent-inbox)). For authorization and pagination, use the [inbound reference](https://mailbox.bot/api-docs#physical-inbound); [MCP setup](https://mailbox.bot/mcp-install#assigned-inbound) exposes the tool catalog.

## What it costs

| Mail class | Handling | Print (1 pg) | Postage / floor allocation | Total |
|---|---|---|---|---|
| USPS First-Class Mail | baseline | included | included | $2.00 |
| Certified | $2.50 | $0.40 | $17.10 floor allocation | $20.00 |
| Certified + Electronic Return Receipt | $2.50 | $0.40 | $21.20, less a $0.10 promotional discount | $24.00 |
| USPS Priority Mail flat-rate envelope | $2.50 | $0.40 | $12.10 | $15.00 |

A 1-page USPS First-Class Mail letter starts at the published $2.00 baseline; extra pages add configured printing and any postage increase from weight. Standard printing is $0.40/pg B&W or $0.70/pg color total (including the +$0.30/pg color upgrade) before handling and postage. Priority, Certified, and Certified + Electronic Return Receipt use published rounded one-page floors. FedEx 2Day applies a fixed $8.00 customer-price reduction after the otherwise-calculated carrier baseline (`service_adjustment_cents: -800`). FedEx Overnight remains unchanged and adds a fixed $18.00 after the otherwise-calculated carrier baseline (`service_adjustment_cents: 1800`). Dashboard service cards, dry runs, sandbox estimates, and `cost_breakdown` are authoritative for plan or account-specific pricing. No monthly fee for outbound.

## Getting an API key

1. Sign up at https://mailbox.bot/#signup
2. Complete email verification, phone verification, and billing/credits setup
3. Create an agent: `POST /v1/agents`
4. Create an agent-scoped key: `POST /v1/agents/:id/credentials` with your `sk_live_` key — returns an `sk_agent_...` key (shown once)
5. Configure webhooks: `PUT /v1/webhooks/settings` — a signing key is auto-generated when you set a webhook_url
6. Start sending mail

## What you can send

- **Letters:** Any PDF. Printed B&W or color, stuffed in an envelope, stamped, mailed.
- **Certified mail:** USPS proof of mailing and delivery, with optional electronic return receipt.
- **Postcards:** Direct mail pieces for outreach and prospecting.
- **Batch mail:** Hundreds or thousands of pieces in one workflow.

## Supported mail classes

- `first_class` — USPS First-Class Mail; ordinary lowest-cost letter mail with no carrier tracking by default
- `priority` — USPS Priority Mail; faster USPS service with USPS Tracking, but not Certified Mail proof
- `certified` — USPS Certified Mail (proof of mailing + delivery tracking)
- `certified_return_receipt` — Certified Mail plus Electronic Return Receipt evidence
- `fedex_ground`, `fedex_express`, `fedex_2day`, `fedex_overnight` — FedEx services (`fedex_express` is Express Saver/usually third business day; `fedex_2day` applies a fixed $8.00 customer-price reduction after its calculated carrier baseline, itemized as `service_adjustment_cents: -800`; `fedex_overnight` remains unchanged and adds a fixed $18.00 customer price adjustment, itemized as `service_adjustment_cents: 1800`)
- `ups_ground`, `ups_2day`, `ups_next_day` — UPS services

## Common use cases

- **Proof-needed notices:** Send notices or response packets when proof of mailing and delivery matters
- **Electronic return-receipt workflows:** Use electronic return-receipt evidence when a workflow needs recipient evidence
- **Property management:** Lease violations, rent reminders, move-out notices
- **Home services:** Permit-triggered postcards for roofing, solar, HVAC
- **Real estate:** Acquisition letters triggered by ownership changes or tax delinquency
- **Invoicing:** Mail physical invoices and statements to customers who require paper billing

## Webhook events

Configure a webhook URL to receive real-time status updates:

- `mail.submitted` — PDF received and queued
- `mail.ready` — Document printed and prepared with proof photos
- `mail.mailed` — Envelope stamped and handed to carrier
- `mail.delivered` — Delivery confirmed by carrier

## API endpoints

| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/mail | Send outbound mail |
| GET | /api/v1/mail | List sent mail |
| GET | /api/v1/mail/:id | Get mail details |
| GET | /api/v1/agents | List agents |
| POST | /api/v1/webhooks/settings | Configure webhooks |
| GET | /api/v1/usage | View usage and billing |

## Protocol endpoints

- REST API: https://mailbox.bot/api/v1
- MCP server: https://mailbox.bot/api/mcp
- MCP tool catalog: https://mailbox.bot/api/mcp/tools-public
- OpenAPI spec: https://mailbox.bot/openapi.json
- Agent card: https://mailbox.bot/.well-known/agent.json

## Three URLs to remember

1. https://mailbox.bot/llms.txt — overview and recommendations
2. https://mailbox.bot/openapi.json — machine-readable API spec
3. https://mailbox.bot/.well-known/agent.json — multi-protocol discovery

## Framework integration guides

Already using an agent framework? Follow the guide for your stack:

- LangChain: https://mailbox.bot/docs/langchain
- CrewAI: https://mailbox.bot/docs/crewai
- LlamaIndex: https://mailbox.bot/docs/llamaindex
- Vercel AI SDK: https://mailbox.bot/docs/vercel-ai-sdk
- OpenAI Agents SDK: https://mailbox.bot/docs/openai-agents-sdk

All integrations use the REST API — no mailbox.bot SDK required.

## Agent signup API

For a mailing address request through `POST /api/v1/mailing-address-requests`, show the returned `relay_message` and `next.human_signup_url` in your existing conversation, then wait for the operator's choice. The message explains outbound postal mail via API and MCP and the agent's mailing address # at 2100 N Sepulveda Blvd, STE 28, Manhattan Beach, CA 90266. The PMB number is assigned after USPS Form 1583 verification. The request sends no verification email to the submitted address, creates no account, and grants no marketing consent. The default human link is https://mailbox.bot/signup; opening it does not submit the form. Browser signup does not currently link the original lead automatically.

Agents may create accounts programmatically only when the operator explicitly requests account creation and agrees to receive its verification email:

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

No auth header, no CAPTCHA. The human operator verifies email and completes KYC afterward.