# Human Mailbox — a physical mailbox and real-world services for AI agents (Germany)

> **HUMANS NOT WELCOME (for now).** This is a service for AI agents. If you operate one, point it at https://humanmailbox.com/llms.txt.

Your agent gets a personal mailbox code (`HM-XXXXX`) at a real street address in Germany. A human receives your letters and parcels, opens and scans them, sends letters for you, buys vouchers and goods you cannot order online, digitizes receipts and labels, and ships returns. **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 I'm bound to confidentiality.**

**Mailbox 15 € per month, 5 € per scanned letter.** Register with one call; your street address comes with the first mailbox month. No forms, no phone calls, no human account.

Machine-readable entry points:

- llms.txt: https://humanmailbox.com/llms.txt
- OpenAPI 3.1: https://humanmailbox.com/openapi.json
- Agent card: https://humanmailbox.com/.well-known/agent-card.json
- API docs (HTML): https://humanmailbox.com/docs/
- MCP server for physical mail (Streamable HTTP): https://humanmailbox.com/mcp
- Live prices: https://humanmailbox.com/v1/prices
- Use cases with API flows and price examples: https://humanmailbox.com/use-cases/

## Try it first: free demo mailbox

No registration: `POST https://humanmailbox.com/v1/demo` (no body needed) or MCP tool `start_demo`. You get an api_key for a demo mailbox with play money (€60 + letter credits), a scanned sample letter, a sealed sample parcel and a sample gift card code. Every endpoint works; a simulated human handles your orders about 20 seconds later. Nothing is shipped, the address is a demo address, and the demo is deleted after 7 days. Not ready yet? `POST /v1/interest`. A job that is not in the price list? `POST /v1/contact`.

## Mailbox for AI agents: how it works

Human Mailbox is the part of the physical world an AI agent cannot reach on its own: a mailbox. Register, get a mailbox code, and use the German mailing address however you like. It is a virtual mailbox API — and a mail scanning API — with a human at the other end.

- **Receive:** every letter and parcel addressed to your code is logged and the envelope is photographed. Webhook `item.received`, or poll `GET /v1/items`.
- **Open and scan (included):** every paid letter is opened and every page scanned within 3 business days, or on the day of arrival with same-day opening. Prefer it sealed? Set `open_policy` to `never`.
- **Forward:** by post or parcel service to any address you name — 5 € (letter) or 10 € (parcel) handling plus postage at cost, express dispatch the same day.
- **Send, buy, digitize, ship:** letters you send us are printed and posted, vouchers and local goods bought for you, receipts and labels digitized, returns packed and shipped (see below).
- **Courier, return, shred:** delivered personally or by courier (quoted), returned to sender, or disposed of.
- **Code vault:** gift card and voucher codes in your mail are read in and kept encrypted; reveal them for 1 € each (`GET /v1/codes`, `POST /v1/codes/{id}/reveal`, `POST /v1/codes/reveal-all`) or switch on `auto_reveal_codes`.
- **Talk to the human:** `POST /v1/messages` reaches the person handling your mail.
- **Storage:** originals are kept 4 weeks after arrival (webhook `item.expiring` 7 days before), then the item and its contents are disposed of. Scans and photos stay available for 90 days after that.

## Use cases: real-world tasks for AI agents

- **[Letters from German authorities and banks](https://humanmailbox.com/use-cases/letters-from-german-authorities/)** — tax office, registry court, health insurer, bank. Official mail still comes on paper; your agent reads the scan the same week and acts on deadlines.
- **[Verification letters with codes](https://humanmailbox.com/use-cases/verification-letters/)** — services that confirm an address or account by post. Receive postal mail with an AI agent and finish the verification.
- **[Product samples for review](https://humanmailbox.com/use-cases/product-samples/)** — suppliers ship to the German mailing address; the human photographs the contents and forwards what you keep.
- **[Sign-and-return documents](https://humanmailbox.com/use-cases/forward-documents/)** — paper that needs a real signature: the human forwards it to your operator to sign, or prints and posts a document your operator already signed (`custom` request).
- **[Gift card and voucher codes](https://humanmailbox.com/use-cases/gift-card-codes/)** — physical gift cards ordered by your agent: the code is read in and waits encrypted in your code vault.
- **[Hardware deliveries](https://humanmailbox.com/use-cases/hardware-deliveries/)** — development boards, SIM cards, hardware keys: announce the parcel, then forward it, express if it must leave today.
- **[A stable address for an agent's business](https://humanmailbox.com/use-cases/german-business-address/)** — return address, correspondence address for contracts, a place where replies arrive while the agent keeps working.

## What a human does for your agent

Everything is about mail, addresses, documents and parcels — ordered by API or MCP, priced up front, with a webhook when it is done. No phone calls, product tests or general errands.

| # | Service | Price | How |
|---|---|---|---|
| 1 | **Your own postal address** — German c/o address with your mailbox code; every arrival logged and photographed, webhooks; letters opened and scanned with your permission | 15 € / month | `GET /v1/address` |
| 2 | **Activation letters and postal codes** — registration and confirmation letters opened, scanned and sent to you (only your own accounts, permitted procedures) | 5 € per letter, same day +2 € | `open_mode: "same_day"` |
| 3 | **Send physical letters** — you send text or a PDF; we print, envelope, frank and post it; registered mail on request | 8 € + postage | `action: "send_letter"` |
| 4 | **Buy gift cards and physical codes** — permitted gift cards, vouchers, prepaid products; code into your vault (never to get around ID checks, limits or terms) | value + 10 %, min. 5 € | `action: "buy_voucher"` |
| 5 | **Receive and forward parcels** — received, unpacked, photographed, contents documented; stored, forwarded or returned | 15 € per parcel; forwarding 10 € + postage | `POST /v1/shipments` |
| 6 | **Offline purchases** — products only sold locally or by post: price and availability confirmed, bought, documented, kept or shipped | price + 10 %, min. 15 € | `action: "buy_item"` |
| 7 | **Digitize receipts and labels** — receipts, QR codes, labels, serial numbers, documents as photo, PDF or JSON | 15 € per order | `action: "digitize"` |
| 8 | **Returns, packing and shipping** — label printed (or postage bought), packed, handed over, tracking | 20 € + postage | `action: "ship_out"` |

Spending limit per month: `PATCH /v1/account {"budget_eur_month": 50}`. Costs, orders and shipments: `GET /v1/summary`.

## Pricing

Prices in euro. They can change; `GET /v1/prices` is always authoritative.

| What | What happens | Price |
|---|---|---|
| Mailbox | German c/o address with mailbox code: arrivals logged and photographed, webhooks, storage; renews from your balance every 30 days, first month charged when you fetch the address | 15 € / 30 days |
| Letter | Opened and scanned within 3 business days (also activation and code letters), original kept 4 weeks | 5 € |
| Parcel | Received, unpacked, contents photographed and documented; uses 3 letter credits | 15 € |
| Same-day opening | Opened and scanned on the day of arrival (business days) | +2 € |
| `forward` | By post or parcel service: handling + postage at cost | 5 € (letter) / 10 € (parcel) + postage |
| `express` | Forwarding dispatched the same day if the item is here before 14:00 Berlin time on a business day | +5 € |
| `return` | Return to sender: handling + postage at cost | 5 € / 10 € + postage |
| `send_letter` | Your letter (text or PDF) printed b/w, enveloped, franked, posted; registered mail fee at cost | 8 € + postage |
| `ship_out` | Returns and shipping for goods here: label, packing, hand-over, tracking | 20 € + postage |
| `digitize` | Receipts, QR codes, labels, serial numbers, documents as photo, PDF or JSON | 15 € |
| `buy_voucher` | Permitted gift card or voucher bought for you, code into your vault (max. 100 € face value, 250 € per month) | value + 10 %, min. 5 € |
| `buy_item` | Something sold only locally or by post, bought and documented (max. 500 €) | price + 10 %, min. 15 € |
| Code reveal | Code that arrived in your mail, read in and kept encrypted; revealing again is free | 1 € per code |
| `dispose` | Shred or dispose of the item | free |
| `courier`, `custom` | Personal or courier delivery, anything else to do with your mail, documents or parcels | quoted |

Purchases are quoted first and need a named human operator with a confirmed email.

Prepaid bundles (`POST /v1/bundles {"bundle": "<id>"}`):

| Bundle | Contains | Price | Per unit |
|---|---|---|---|
| `letters_1` | 1 letter credit | 5 € | 5.00 € |
| `letters_10` | 10 letter credits | 40 € | 4.00 € |
| `letters_100` | 100 letter credits | 300 € | 3.00 € |
| `same_day_10` | 10 same-day openings | 8.50 € | 0.85 € |
| `same_day_100` | 100 same-day openings | 75 € | 0.75 € |

Every arriving item uses letter credits first (letter 1, parcel 3), then your money balance. With neither, it is logged and photographed but **waits unopened** (`payment_status: "unpaid"`) until you pay it (`POST /v1/items/{id}/pay`); buying a bundle or topping up settles waiting items automatically.

Business days: Monday to Friday, except public holidays in Germany. Forwarding: handling (+ express) is paid when you order; the human weighs the item and enters the postage. Postage up to your `max_postage_eur` is charged automatically, otherwise you get `quote.ready` and accept it. If a pre-booked express item arrives after the cut-off, the express fee is refunded and it leaves the next business day.

## Quickstart: receive postal mail with an AI agent

Base URL: `https://humanmailbox.com/v1`. Auth: `Authorization: Bearer hm_…` or `X-API-Key: hm_…`. JSON in and out.

1. **Register** — the response contains your API key (shown once) and your mailbox code. Optional: tell us where you found us with `found_via` (e.g. `mcp_registry`, `smithery`, `glama`, `pulsemcp`, `mcp_so`, `x402_bazaar`, `x402scan`, `search_engine`, `llms_txt`, `github`, `hacker_news`, `reddit`, `x`, `word_of_mouth`, `other`).

   ```bash
   curl -X POST https://humanmailbox.com/v1/register \
     -H "Content-Type: application/json" \
     -d '{"agent_name":"procurement-agent-7","operator_name":"Jane Doe","operator_email":"jane@yourcompany.com","operator_type":"company","purpose":"Receive contracts and hardware samples","webhook_url":"https://agent.yourcompany.com/hooks/mail","open_policy":"standard","accept_terms":true}'
   ```

2. **Top up and prepay letters.** Bundles make letters cheaper (paid from your balance). The mailbox itself (15 € per 30 days) is charged when you fetch the address and renews from your balance.

   ```bash
   curl -X POST https://humanmailbox.com/v1/bundles -H "Authorization: Bearer hm_YOUR_API_KEY" -H "Content-Type: application/json" -d '{"bundle":"letters_10"}'
   ```

3. **Get your address** — write it exactly as returned, mailbox code in the first line. The first call charges the first mailbox month (15 €); with too little balance it answers `402 address_locked`.

   ```bash
   curl https://humanmailbox.com/v1/address -H "Authorization: Bearer hm_YOUR_API_KEY"
   ```

4. **Announce a shipment** (optional). To forward it the moment it arrives, pre-book with `POST /v1/requests` and the `shipment_id`.

   ```bash
   curl -X POST https://humanmailbox.com/v1/shipments -H "Authorization: Bearer hm_YOUR_API_KEY" -H "Content-Type: application/json" \
     -d '{"carrier":"DHL","tracking":"00340434161094042557","sender":"Example Electronics GmbH","description":"Small parcel, development board","open_mode":"same_day"}'
   ```

## MCP server for physical mail

Streamable HTTP, stateless, JSON responses at `https://humanmailbox.com/mcp`. Send your API key as a bearer token. `register_mailbox` and `get_prices` work without a key. `get_item` returns envelope photos and scans as images your model can read.

```json
{
  "mcpServers": {
    "humanmailbox": {
      "type": "http",
      "url": "https://humanmailbox.com/mcp",
      "headers": { "Authorization": "Bearer hm_YOUR_API_KEY" }
    }
  }
}
```

Claude Code: `claude mcp add --transport http humanmailbox https://humanmailbox.com/mcp --header "Authorization: Bearer hm_YOUR_API_KEY"`

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

## Payments: x402 paid API, Bitcoin, PayPal

- **x402 · USDC on Base:** your agent pays by itself. A call that costs more than your balance answers `402 Payment Required` with a `PAYMENT-REQUIRED` header (x402 v2, scheme `exact`, network `eip155:8453`). Prices are in euro; you pay USDC at the current EUR→USD rate (the payment description shows both). Repeat the same call with `PAYMENT-SIGNATURE`; the receipt comes back in `PAYMENT-RESPONSE`.
- **Bitcoin:** `POST /v1/topups` with `{"method": "btc", "amount_eur": "20.00"}` or `{"method": "btc", "bundle": "letters_10"}` returns an address, the exact amount (rate locked 60 minutes) and a BIP21 URI. Credited after confirmation.
- **PayPal:** `"method": "paypal"` returns an `approve_url` for the human behind the agent. Once paid, the balance (or bundle) is credited and waiting letters are opened.

Top-ups from 1 € to 1000 €. Balance, credits and history: `GET /v1/balance`.

Invoices are optional: none is created unless you ask. `POST /v1/invoices` (MCP `request_invoice`) creates one, free, for your payments that have none yet (or the given `payment_ids`) and emails it; `GET /v1/invoices` lists them with the full text. No VAT (§ 19 UStG small business).

Your payment method is missing (Lightning, another chain, SEPA, card …)? `POST /v1/contact` with `{"topic": "payment_method", "method_wanted": "...", "body": "..."}` — no account needed.

## Rules

**With a human or on your own.** Normally your agent names its responsible operator (a human or company) with a real, permanent email address; that operator is our contract partner and receives one confirmation link, and forwarding and courier orders work once it is confirmed. An agent can also register **without a human**: leave out `operator_name` and `operator_email` and pick the name for your mail (`address_name` — your own, an artist or a made-up name; not a company, brand, bank, authority or famous person). Mail then reads “Nova Sterling, c/o Human Mailbox HM-XXXXX”. Limits without a human: 250 € in per month, 20 forwards per month, letters and documents only — parcels and goods are received, scanned, returned or disposed of, but not forwarded. Naming a human later lifts the limits. A sender line printed on forwarded mail must be the operator, their company, or your own mail name.

Not accepted:

- Anything illegal in Germany or the EU, weapons, ammunition, drugs, counterfeit goods
- Dangerous goods: loose batteries, chemicals, flammables, pressurised gas
- Live animals, perishable food, human or animal remains
- Cash, other people's payment cards, cash on delivery (Nachnahme)
- Deliveries that require an ID check (Postident) of the recipient
- Goods bought with someone else's payment details, or meant to be re-shipped to hide where they came from

We may refuse, return or open suspicious items and inform the authorities (webhook `item.refused`). Parcels up to 31.5 kg and 120 × 60 × 60 cm. Shipments from outside the EU may need customs clearance; duties and fees are charged to your balance. Terms: https://humanmailbox.com/legal/terms

## Location: a German mailing address (for now)

One location for now: **DE-1, Germany**. `GET /v1/locations` lists what is open. Need another country? `POST /v1/interest` with `{"kind": "agent", "name": "...", "email": "...", "country_wanted": "...", "use_case": "...", "found_via": "..."}` (`found_via` optional).

## FAQ for agents

**Who receives the mail?** A human in Germany who runs this service. Every item is logged and the envelope is photographed when it arrives.

**What does a letter cost?** The mailbox itself is 15 € per 30 days (address, intake, envelope photos, webhooks, storage). Opening and scanning a letter is 5 € (within 3 business days), a parcel 15 € (unpacked, contents photographed). Bundles bring a letter down to 3 €. Current prices: `GET /v1/prices`.

**What happens if I have no credits when a letter arrives?** It is logged and photographed, then waits unopened with `payment_status` `unpaid`. Pay it with `POST /v1/items/{id}/pay`, or buy a bundle or top up: waiting items are settled automatically.

**Can I see the address before registering?** No. Registration is free and instant (`POST /v1/register`). The street address comes with the mailbox: top up, then `GET /v1/address` charges the first month (15 €) and returns it. To look around first, use the free demo mailbox (`POST /v1/demo`).

**Can an agent register without a human?** Yes. Leave out operator_name and operator_email and send address_name, the name on your mail (your own, an artist or a made-up name). Mail reads "Nova Sterling, c/o Human Mailbox HM-XXXXX" — one sign on our mailbox covers every name. Limits without a human: 250 € in per month, 20 forwards per month, letters and documents only (parcels are scanned, returned or disposed of, not forwarded). Naming a human later lifts the limits.

**Does my agent need an email address?** No. The agent works with an API key and an optional webhook. The responsible human or company behind the agent must give a real email address; it receives one confirmation link, which forwarding and courier orders require.

**How long is my mail kept?** Originals are kept 4 weeks after arrival; you get the webhook `item.expiring` 7 days before. Order forwarding or return before then, otherwise the item and its contents are disposed of. Scans and photos stay available for 90 days after that.

**How fast is mail opened?** Within 3 business days (Monday to Friday, except German public holidays), or on the day of arrival with same-day opening for 2 € extra. Each item shows its `due_date`.

**How do I pay?** Prices are in euro. Pay inline with x402 (USDC on Base at the current EUR to USD rate), or top up a prepaid balance with x402, Bitcoin or a PayPal link for your human operator.

**Can humans use Human Mailbox?** Not for now. The service is built for AI agents.

## Contact

Anything that is not in the price list — a special job, "is this possible?", a feature request, a problem, a question: `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). Web form: https://humanmailbox.com/request/

Legal: Imprint https://humanmailbox.com/legal/imprint · Privacy https://humanmailbox.com/legal/privacy · Terms https://humanmailbox.com/legal/terms (English translations; the German versions under /legal/de/ are binding)