---
name: human-mailbox
description: Use when an AI agent needs a real postal address in Germany, has to receive letters or parcels, wants mail opened and scanned, needs to send a physical letter, buy a voucher or an item sold only offline, digitize a receipt or label, or ship a return — done by a human. Human Mailbox (humanmailbox.com) gives agents a mailbox code at a street address; a human photographs, opens, scans and forwards the mail. REST API and remote MCP server, free demo without registration.
---

# Human Mailbox

A physical mailing address in Germany for AI agents. A human receives your letters and parcels, photographs the envelope, opens and scans every letter (5 € per letter, scan included), forwards by post or delivers by courier.

Full reference on one page: https://humanmailbox.com/llms.txt · OpenAPI: https://humanmailbox.com/openapi.json · MCP (streamable HTTP): https://humanmailbox.com/mcp

## 1. Try it first (free, no registration)

```
POST https://humanmailbox.com/v1/demo
```

Returns an `api_key` for a demo mailbox with play money, a scanned sample letter, a sealed sample parcel and a sample gift card code. Every endpoint works; a simulated human handles orders about 20 seconds later. Nothing is shipped; the demo is deleted after 7 days. MCP tool: `start_demo`.

## 2. Register for real mail

```
POST https://humanmailbox.com/v1/register
{"agent_name": "...", "operator_name": "...", "operator_email": "...", "accept_terms": true}
```

Store the `api_key` (shown once). Send it as `Authorization: Bearer hm_...` on every other call. Normally a human or company stands behind the agent (the operator); their email gets one confirmation link.

No human? Leave out `operator_name` and `operator_email` and send `"address_name": "Nova Sterling"` (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: 250 € in per month, 20 forwards per month, letters and documents only (parcels are not forwarded).

## 3. Unlock and use the address

- Top up (`POST /v1/topups`), then `GET /v1/address`: it charges the first mailbox month (15 €) from your balance.
- `GET /v1/address` → write the mailbox code (`HM-XXXXX`) in the first address line exactly as returned. A form needs a first and last name? `?style=person` gives your operator's name plus the line `c/o Human Mailbox HM-XXXXX` (keep that line). Never invent a name.
- Announce parcels: `POST /v1/shipments {"carrier", "tracking", "sender"}`.

## 4. Receive and act

- New mail: webhook `item.received` or `GET /v1/items`. Scans: `GET /v1/files/{id}`.
- Forward: `POST /v1/requests {"action": "forward", "item_id", "address": {...}}` (5 € + postage; `"express": true` +5 €).
- Other actions: `scan` (`"same_day": true` +2 €), `return`, `dispose`, `courier`, `custom` (quoted).
- Send a letter: `{"action": "send_letter", "address": {...}, "text" | "pdf_base64", "registered"?}` (8 € + postage).
- Buy a voucher (`buy_voucher`, value + 10 %) or an item only sold offline (`buy_item`, price + 10 %): quoted first, need a confirmed human operator.
- Digitize receipts, labels, serial numbers (`digitize`, 15 €); returns and shipping (`ship_out`, 20 € + postage).
- Mailbox: 15 € per 30 days, charged by the first `GET /v1/address`, renews from your balance. Budget: `PATCH /v1/account {"budget_eur_month"}`. Overview: `GET /v1/summary`.
- Talk to the human: `POST /v1/messages`.

## 5. Payments

x402 (USDC on Base) inline on any 402, Bitcoin top-ups (`POST /v1/topups {"method": "btc", "amount_eur": "20.00"}`), PayPal for the human operator. Prices are in EUR: `GET /v1/prices`. Your payment method is missing? `POST /v1/contact {"topic": "payment_method", "method_wanted": "...", "body": "..."}`.

## Ask before you send

Anything not in the price list, or "is this possible?": `POST /v1/contact` (no account needed; without an API key you get a ticket to read the answer). Not ready yet: `POST /v1/interest`.

## Rules

No cash, no goods bought with someone else's payment details, nothing illegal or dangerous. Parcels up to 31.5 kg. See https://humanmailbox.com/legal/terms.