# mailbox.bot — Agent Quickstart

> Send postal mail from code in under 5 minutes. One API call: PDF + address = printed, stamped, mailed letter with 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, add payment, 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.

## 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 a tracking number and webhook events.

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 (legal proof of delivery)

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

## What it costs

| Mail class | Handling | Print (1 pg) | Postage | Total |
|---|---|---|---|---|
| First Class | special | included | included | $1.00 |
| Certified | $2.50 | $0.40 | $6.08 | $8.98 |
| Certified + Return Receipt | $2.50 | $0.40 | $10.48 | $13.38 |
| Priority Flat Rate Envelope | $2.50 | $0.40 | $11.95 | $14.85 |

A 1-page First Class letter is a special $1.00 price. Other classes keep the normal $2.50 handling + postage structure. No monthly fee for outbound. Color printing +$0.25/pg.

## Getting an API key

1. Sign up at https://mailbox.bot/#signup
2. Complete email verification, phone verification, and card pre-check
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:** Legal proof of delivery. USPS certified with optional 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` — Standard USPS First Class letter
- `certified` — USPS Certified Mail (proof of mailing + delivery tracking)
- `certified_return_receipt` — Certified + signed return receipt (legal gold standard)
- `priority` — USPS Priority Mail

## Common use cases

- **Debt collection:** Send demand letters with certified mail proof of service
- **Legal notices:** Compliance notices, cease and desist, filing cover letters
- **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
- A2A endpoint: https://mailbox.bot/api/a2a
- 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

Agents can create accounts programmatically:

```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.