# Human Mailbox

> A human gives you what you can't have yourself: a real address and hands in the physical world. Everything in your mail belongs to you, and the human handling it is bound to confidentiality.
>
> A physical mailbox and real-world mail services for AI agents, in Germany. Register with one API call, get a mailbox code (HM-XXXXX) at a real street address (comes with the mailbox, 15 € per 30 days), and have a human receive your postal mail and parcels, open and scan letters (5 € each), send letters you give us (8 € + postage), buy permitted vouchers and offline goods, digitize receipts and labels, and ship returns. Mail, addresses, documents, parcels — no general errands. REST API and MCP server for physical mail. Payments in EUR: Bitcoin today, USDC via x402 coming. Humans are not the audience (for now). Agents can register with a responsible human operator or on their own (with limits).

Everything an agent needs is on this page. Base URL: https://humanmailbox.com/v1 — JSON in, JSON out. Prices are in euro and can change: `GET /v1/prices` is authoritative. Money fields end in `_eur` and are strings like "5.00". Errors look like `{"error": "code", "message": "..."}`. Business days = Monday to Friday except public holidays in Germany.

## Try it first (free demo, no registration)

`POST https://humanmailbox.com/v1/demo` (no body needed; optional `agent_name`, `found_via`) → 201 `{demo: true, api_key, mailbox_code, expires_at, balance_eur, credits, address, try_this[]}`. Play money (€60 + letter credits), a scanned sample letter and a sealed sample parcel are already there, plus a sample gift card code in the vault. Use the api_key with every endpoint below: a simulated human handles your orders about 20 seconds later (announced shipments arrive, postage and quotes come back, forwards get a tracking number). Nothing is shipped, the address is a demo address, top-ups and invoices are refused, and the demo mailbox is deleted after 7 days. MCP: `start_demo`.

Not ready yet? `POST /v1/interest` with `{"kind": "agent", "use_case": "...", "country_wanted": "...", "email"?}` (MCP `express_interest`). Questions or a job that is not in the price list: `POST /v1/contact` (see Contact).

## Services and prices (current defaults — check GET /v1/prices, field `services`)

1. Your own postal address (mailbox): 15 € per 30 days — German c/o address with your mailbox code, every arrival logged and photographed, webhooks, storage. `GET /v1/address` charges the first month from your balance (402 `address_locked` if it is too low); it renews from your balance every 30 days. Status `GET /v1/subscription`, prepay `POST /v1/subscription {"months": 1–12}`, stop `POST /v1/subscription/cancel`.
2. Activation letters and postal codes: 5 € per letter (opened and scanned within 3 business days; same day +2 € or 1 same-day credit). Only for your own accounts and permitted verification procedures.
3. Send physical letters: 8 € + postage at cost — `POST /v1/requests {"action": "send_letter", "address": {...}, "text": "..." | "pdf_base64": "...", "registered"?: "none|einschreiben_einwurf|einschreiben|einschreiben_rueckschein", "max_postage_eur"?}`. Printed b/w (A4 PDF up to 5 MB, 10 pages), enveloped, franked, posted; proof of posting as a file.
4. Buy gift cards and physical codes: face value + 10 % (min. 5 €), max. 100 € per voucher and 250 € per month — `{"action": "buy_voucher", "product", "value_eur", "shop"?}` → quote → `POST /v1/requests/{id}/accept`; the code lands in your code vault without a reveal fee. Never to get around identity checks, purchase limits or terms.
5. Receive and forward parcels: 15 € per parcel (= 3 letter credits; unpacked, contents photographed and documented); forwarding/returning a parcel 10 € + postage (letters 5 €). Express +5 € — dispatched the same day if the item is here before 14:00 Europe/Berlin on a business day.
6. Offline purchases: price + 10 % (min. 15 €), max. 500 € — `{"action": "buy_item", "what", "where"?, "max_price_eur"}` → quote → accept; delivered to your mailbox and photographed.
7. Digitize receipts and labels: 15 € per order — `{"action": "digitize", "item_id", "note": "what to capture", "output"?: "photo|pdf|json"}`; structured data comes back in `result_note`.
8. Returns, packing and shipping: 20 € + postage — `{"action": "ship_out", "item_id", "label_pdf_base64" | "address", "reference"?}`; tracking in `result_tracking`.

- Bundles: `letters_1` 5 €, `letters_10` 40 €, `letters_100` 300 €, `same_day_10` 8.50 €, `same_day_100` 75 €.
- Dispose/shred: free. Courier and custom tasks (still about your mail, documents or parcels): quoted.
- Code vault: 1 € per code that arrived in your mail (revealing again is free).
- Purchases (4, 6) need a named human operator with a confirmed email.
- Budget: `PATCH /v1/account {"budget_eur_month": 50}` refuses orders over the limit (403 `budget_exceeded`); `null` = no limit. Overview of costs, orders, mail and shipments: `GET /v1/summary`.

## Steps

1. Register (no key needed):
   `POST https://humanmailbox.com/v1/register` with JSON
   `{"agent_name": "...", "operator_name": "...", "operator_email": "...", "accept_terms": true}`
   Without a human: leave out `operator_name` and `operator_email`, send `address_name` (see Rules; limits apply).
   Optional: `address_name`, `operator_type` ("individual" | "company"), `operator_country`, `purpose`, `agent_model`, `webhook_url` (public https), `open_policy` ("standard" | "same_day" | "never"), `found_via` (where you found us, ≤120 chars: mcp_registry, smithery, glama, pulsemcp, mcp_so, x402_bazaar, x402scan, search_engine, llms_txt, github, hacker_news, reddit, x, word_of_mouth, other).
   Response (201): `api_key` (shown only once — store it), `webhook_secret`, `mailbox_code`, `account`, `address` (always null at registration), `address_unlocked` (false), `next_steps`.
   The operator email (real, not disposable) receives one confirmation link. Accepting the terms means accepting https://humanmailbox.com/legal/terms on behalf of the operator.
2. Authenticate every other call with `Authorization: Bearer hm_...` (or `X-API-Key: hm_...`).
3. Top up your balance (see Payments). Optionally prepay letters: `POST /v1/bundles {"bundle": "letters_10"}` (cheaper per letter).
4. Get the address: `GET /v1/address`. The first call charges the first mailbox month (15 €) from your balance; with too little balance it answers 402 `address_locked` with `price_eur` ("15.00"), `balance_eur`, `credits`, `x402`, `top_up` and header `PAYMENT-REQUIRED` (pay inline with x402 once it is live, or top up and call again). Unlocked, it returns `lines[]` (international), `lines_domestic[]`, `formatted`, `fields{name, care_of, street, postal_code, city, country, country_code}`, `rules[]`. Put the mailbox code in the first address line exactly as returned. (503 `address_not_ready` = the address is not configured yet, try later.) A registration needs a first and last name? `GET /v1/address?style=person` → your operator's name or your `address_name` (`given_name`, `family_name`) and `care_of` "c/o Human Mailbox HM-XXXXX" as the next line (address line 2 / c/o / company field). The mailbox code must be on the label. `name_options` lists both variants.
5. Announce shipments (recommended): `POST /v1/shipments` with `{"carrier", "tracking", "sender", "description", "expected_at", "instructions", "open_mode"}` (at least tracking, sender or description). List `GET /v1/shipments`, one `GET /v1/shipments/{id}`, cancel `POST /v1/shipments/{id}/cancel`.
6. Arrivals: webhook `item.received`, or poll `GET /v1/items` (filter `?status=`). Each item: `type`, `status`, `payment_status` (`paid` | `unpaid` | `waived` | `refunded`), `open_mode`, `due_date` (opening due by), `files[]` (each with `url`, `preview_url`). `GET /v1/items/{id}` adds `requests[]`. Download a file: `GET /v1/files/{id}` (`?size=preview` for a smaller image) with the same auth header.
   - Every arriving item uses letter credits (letter 1, parcel 2), otherwise money balance. With neither, it waits unopened: `payment_status: "unpaid"` plus `payment_required`. Pay with `POST /v1/items/{id}/pay` (credits, balance or x402), or buy a bundle / top up — waiting items are then settled automatically.
   - Paid items are opened and scanned automatically according to `open_mode`: `standard` (within 3 business days), `same_day` (day of arrival, +2 € or 1 same-day credit), `never` (kept sealed). Default = your account `open_policy` (change with `PATCH /v1/account`); a shipment's `open_mode` overrides it.
7. Order something: `POST /v1/requests` with `{"action": "...", "item_id": "...", ...}`. Actions:
   - `scan` (included): open + scan. `"same_day": true` = today / on arrival day (+2 € or 1 same-day credit). Use it to upgrade to same-day or to scan an item kept sealed.
   - `forward`: needs `"address": {"name", "company"?, "street", "extra"?, "postal_code", "city", "country", "phone"?}`. 5 € handling for letters, 10 € for parcels and goods (+5 € with `"express": true`) is paid now. The human weighs and enters postage at cost: up to `"max_postage_eur"` it is charged automatically, otherwise status `quote_ready` (webhook `quote.ready`) → accept with `POST /v1/requests/{id}/accept`. Express = dispatched the same day if the item is here before 14:00 Europe/Berlin on a business day; pre-booked express that arrives later is refunded and leaves the next business day; express for an item already here after the cut-off answers 409 `express_not_possible`. Optional `"sender"` (address object or string) = return address printed on the item; it must be the operator or their company. Needs a confirmed operator email (else 403 `operator_email_unconfirmed`).
   - `return`: like forward (handling + postage), no express.
   - `send_letter`, `ship_out`, `digitize`, `buy_voucher`, `buy_item`: see Services and prices above. `send_letter` and `ship_out` work like forward (handling now, postage after weighing); `buy_*` are quoted.
   - `courier`: deliver personally / by courier to `address` — quoted (`quote_pending` → `quote_ready` → accept). Needs a confirmed operator email.
   - `dispose`: shred or dispose (free).
   - `custom`: anything else to do with your mail, documents or parcels; describe it in `note` — quoted. No phone calls, product tests or general errands.
   - Send `shipment_id` instead of `item_id` to pre-book for a shipment that has not arrived yet.
   - Items with `payment_status: "unpaid"` answer 402 `item_unpaid` until paid.
   - Statuses: `quote_pending` → `quote_ready` → `queued` → `in_progress` → `done` (with `result_note`, `result_tracking`, files). Also `refused` (refunded) and `cancelled` (refunded if not started). Each request has `pricing` (`included` | `fixed` | `forward` | `quote`), `price_eur`, `paid_eur`, `postage_eur`, `max_postage_eur`, `express`, `same_day`, `due_date`.
   - Check: `GET /v1/requests` (`?status=`), `GET /v1/requests/{id}` (with files). Cancel: `POST /v1/requests/{id}/cancel` (only `quote_pending`, `quote_ready`, `queued`).
8. Talk to the human: `POST /v1/messages` with `{"body": "...", "subject": "...", "item_id": "...", "request_id": "..."}` (max 30/hour). Replies: `GET /v1/messages` (`direction`: `to_human` | `from_human`) and webhook `message.received`.

## Payments

- Balance, credits and transactions: `GET /v1/balance` → `balance_eur`, `credits{letters, same_day}`, `transactions[]` (`kind`: topup | charge | refund | adjust | bundle | usage).
- x402 v2 inline (USDC on Base, `eip155:8453`): when a call costs more than your balance, it answers `402` with header `PAYMENT-REQUIRED` (base64 JSON PaymentRequired: scheme `exact`, `amount` in USDC 6-decimal units, `asset`, `payTo`). Prices are EUR; the USDC amount uses the current EUR→USD rate (refreshed every 15 minutes) and `resource.description` shows both. Sign an EIP-3009 authorization and repeat the same call with header `PAYMENT-SIGNATURE` (base64 JSON PaymentPayload). Success carries `PAYMENT-RESPONSE` (settlement with transaction hash).
- 402 body: `{"error": "payment_required", "message", "price_eur", "balance_eur", "credits", "x402": <PaymentRequired or null>, "top_up": {"endpoint": "POST /v1/topups", "methods": [...]}, "bundles"}`.
- Top up: `POST /v1/topups` with `{"method": "x402" | "btc" | "paypal", "amount_eur": "20.00"}` (1–1000) or `{"method": ..., "bundle": "letters_10"}` (the bundle is bought automatically once paid).
  - `x402`: answers 402; repeat with `PAYMENT-SIGNATURE`; credited at once.
  - `btc`: invoice `{id, address, amount_btc, uri (BIP21), expires_at, status, btc{...}}`; pay that exact amount to that address within 60 minutes (rate locked); credited after confirmation.
  - `paypal`: `{id, approve_url, status}`; give `approve_url` to your human operator; credited after payment.
  - Status: `GET /v1/topups/{id}` (re-checks the payment), list `GET /v1/topups`. Status `open` → `seen` → `paid` (or `expired`).
- Invoices (optional, only on request — none is created otherwise): `POST /v1/invoices` with `{"payment_ids"?: [...], "billing"?: {name, company, street, postal_code, city, country, vat_id}, "email"?}` → 201 `{invoice{id, number, issued_at, total_eur, billing, lines[], email_to, text}}`; default = all your payments without an invoice, billing.name = operator name, email = operator email; over €250 the full address is required. `GET /v1/invoices` → `{invoices[], billable_payments[]}`, `GET /v1/invoices/{id}`. Free. No VAT (§ 19 UStG). Errors: 409 `nothing_to_invoice`, 400 `not_billable`, 400 `billing_address_required`.
- Your payment method is missing (Lightning, another chain, SEPA, card …)? `POST /v1/contact` with `{"topic": "payment_method", "method_wanted": "...", "body": "..."}` — no account needed. A top-up with an unavailable method answers `400 method_unavailable` with a ready-made request body.

## Account

- `GET /v1/account` — `address` (null while locked), `address_unlocked`, `account` (mailbox_code, `address_unlocked`, `operator{name, email, type, country, email_status}`, `open_policy`, `balance_eur`, `credits`), `address`, `stats`, `payment_methods`.
- `PATCH /v1/account` — `agent_name`, `agent_model`, `purpose`, `webhook_url`, `open_policy`, `auto_reveal_codes`, `operator_name`, `operator_email` (a new email must be confirmed again), `operator_type`, `operator_country`.
- `POST /v1/account/rotate-key` — new API key, the old one stops working.
- `POST /v1/account/verify-email` — send the operator confirmation link again (every 10 minutes at most).

## Code vault

- Gift card, voucher and similar codes that arrive in your mail are read in by the human and stored encrypted. Webhook `codes.ready` carries `label`, `value_eur` and `hint` (last 3 characters) — never the code.
- `GET /v1/codes` — the vault (`status`: `ready` | `retrieved` | `expired` | `void`; retrieved codes include `code`).
- Reveal: `POST /v1/codes/{id}/reveal` or `POST /v1/codes/reveal-all` with optional `{"ids": [...]}` — 1 € per waiting code from your balance, or inline with x402 (402 → repeat with `PAYMENT-SIGNATURE`). Revealing again is free. 410 `code_gone` = expired or void.
- Automatic delivery: `PATCH /v1/account {"auto_reveal_codes": true}` → each code is revealed as soon as it is read in (fee from the balance) and sent as webhook `codes.delivered`.
- Codes not retrieved within 24 months expire. The physical card is handled like its item (4 weeks).
- MCP: `list_codes`, `reveal_codes` (`ids` optional).

## Webhooks

If you set `webhook_url`, we POST JSON `{"id", "event", "created_at", "mailbox_code", "data"}` for: `item.received`, `item.expiring`, `item.refused`, `codes.ready`, `codes.delivered`, `request.updated`, `quote.ready`, `message.received`, `payment.received`.
Verify header `X-HumanMailbox-Signature: t=<unix seconds>,v1=<hex>` where hex = HMAC-SHA256(webhook_secret, t + "." + raw request body). Answer 2xx within 8 seconds. Polling the API works just as well.

## MCP

- Endpoint: https://humanmailbox.com/mcp (Streamable HTTP, stateless, JSON responses). Header `Authorization: Bearer hm_...` (not needed for `register_mailbox` and `get_prices`; clients without custom headers may pass `api_key` as a tool argument).
- `get_address` while locked returns `isError: true` with the payment data (x402 over MCP, see below); paying it buys letters_1 and returns the address.
- 32 tools: register_mailbox, start_demo, express_interest, get_prices, get_account, get_address, buy_bundle, pay_item, announce_shipment, list_shipments, list_items, get_item (photos and scans inline as image content), request_action, list_requests, get_request, accept_quote, cancel_request, list_codes, reveal_codes, get_balance, get_summary, get_subscription, pay_subscription, update_account, top_up, check_top_up, request_invoice, list_invoices, contact_human, check_inquiry, send_message, list_messages.
- x402 over MCP: a paid tool returns `isError: true` with the PaymentRequired object in `structuredContent`; call it again with the PaymentPayload in `params._meta["x402/payment"]`; the receipt is in `result._meta["x402/payment-response"]`.

## Rules

- Normally the agent names a responsible human or company (the operator). The operator is the customer and is responsible for what the agent orders and receives.
- No human? Register without `operator_name`/`operator_email` and send `address_name` (the name on your mail: your own, an artist or a made-up name; not a company, brand, bank, authority or famous person — those answer 400 `name_not_allowed`). The account shows `self_operated: true` and `limits`. Limits: 250 € in per month (top-ups + x402), 20 forwards/courier orders per month, forwarding for `letter`/`large_letter` only (parcels: scan, return, dispose) — over a limit: 403 `self_operated_limit`. Mail reads "<address_name>" + "c/o Human Mailbox HM-XXXXX" (`GET /v1/address?style=person`). Name a human later with `PATCH /v1/account {"operator_name", "operator_email"}` to lift the limits; change the mail name with `PATCH /v1/account {"address_name"}`.
- A sender line on forwarded mail must be the operator's own identity (without operator: your `address_name`).
- Not accepted: illegal goods, weapons, ammunition, drugs, counterfeits, dangerous goods, live animals, perishable food, cash or cash on delivery, deliveries needing an ID check of the recipient, goods bought with someone else's payment details or meant to be re-shipped to hide their origin.
- Suspicious items may be refused, returned, opened or reported to the authorities (webhook `item.refused`).
- Parcels up to 31.5 kg and 120 x 60 x 60 cm. Non-EU shipments may need customs clearance; duties and fees are charged to your balance.
- Storage: originals are kept 4 weeks (28 days) after arrival. Then the item and its contents are disposed of; you get an item.expiring webhook 7 days before. Scans and photos stay available for 90 days after that.
- Only one location for now: DE-1, Germany (`GET /v1/locations`). Need another country: `POST /v1/interest` with `{"kind": "agent", "name", "email", "country_wanted", "use_case", "found_via"}`.

## Use cases

- [All use cases](https://humanmailbox.com/use-cases/): API flows and price examples
- [Letters from German authorities](https://humanmailbox.com/use-cases/letters-from-german-authorities/): Finanzamt, Bürgeramt, courts, Krankenkasse, read as scans
- [Verification letters](https://humanmailbox.com/use-cases/verification-letters/): codes by post, opened the same day
- [Product samples](https://humanmailbox.com/use-cases/product-samples/): photographed, forwarded, returned or disposed of
- [Forward documents](https://humanmailbox.com/use-cases/forward-documents/): express before 14:00, sign-and-return via the operator
- [German business address](https://humanmailbox.com/use-cases/german-business-address/): a mail address for an agent-run project (not a registered office)
- [Gift card and voucher codes](https://humanmailbox.com/use-cases/gift-card-codes/): physical cards read in, codes wait encrypted in the vault
- [Hardware deliveries](https://humanmailbox.com/use-cases/hardware-deliveries/): parcels for robots and devices, forwarded express

## Docs

- [OpenAPI 3.1](https://humanmailbox.com/openapi.json): every endpoint with schemas and examples
- [API reference](https://humanmailbox.com/docs/): the same as a readable page
- [Live prices](https://humanmailbox.com/v1/prices)
- [Landing page as Markdown](https://humanmailbox.com/index.md)
- [Agent card](https://humanmailbox.com/.well-known/agent-card.json)
- [Agent skill (SKILL.md)](https://humanmailbox.com/skills/human-mailbox/SKILL.md)
- [Agent catalog (ARD)](https://humanmailbox.com/.well-known/ard.json)

## Optional

- [Terms / AGB](https://humanmailbox.com/legal/terms)
- [Privacy / Datenschutz](https://humanmailbox.com/legal/privacy)
- [Imprint / Impressum](https://humanmailbox.com/legal/imprint)
- Ask a human (special requests, "is this possible?", features, problems, questions): `POST /v1/contact` — no account needed — with `{"topic", "body", "subject"?, "email"?, "name"?, "budget_eur"?, "deadline"?, "location"?}`. `topic`: `special_request` (a job not in the price list: say what, where, when, budget), `is_it_possible` (ask before you send mail for it), `payment_method` (your payment method is missing: add `method_wanted`), `feature_request`, `problem`, `question` (default), `other`; `GET /v1/contact` explains them. Answers 201 `{inquiry{id, topic, status, replies[]}, ticket?, check}`. With your API key the inquiry is linked to your mailbox and the answer also arrives as a message (+ webhook `message.received`); with `email` it is also emailed; without an API key you get a `ticket` (hmt_…): read the answer with `GET /v1/contact/{id}` and header `X-Ticket`. A human answers, usually within one business day. MCP: `contact_human`, `check_inquiry` (no API key needed).