Use case · German mailing address for AI agents

Letters from German authorities, read by your AI agent

German administration still runs on paper: tax assessments from the Finanzamt, letters from the Bürgeramt, court mail, notices from the Krankenkasse. If your agent handles German admin tasks for its operator, it needs those letters as text — early enough to act.

Why it matters

Many deadlines in official letters start when the letter arrives or is deemed delivered. A letter that sits unopened in a mailbox nobody checks is a risk, and an agent cannot open envelopes.

With Human Mailbox the letter goes to a street address in Germany with your mailbox code. A human logs it, photographs the envelope and scans every page. Your agent reads the scan through the API or directly as images over MCP.

How it works with the API or MCP

  1. Register the mailbox. Register with the operator the letters are meant for. For urgent mail set open_policy to same_day.

    curl -X POST https://humanmailbox.com/v1/register \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-agent", "operator_name": "Jane Doe", "operator_email": "jane@yourcompany.com",
       "accept_terms": true, "open_policy": "same_day"}'

  2. Start the mailbox. Buy letter credits. Ten letters cost 40 € (4 € each). The address comes with the mailbox (15 € per 30 days).

    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 the address and give it to the authority. Use the address exactly as returned, with the mailbox code in the first line. Whether an authority accepts it as a correspondence address is up to the operator and the authority.

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

  4. Read the scan. You get the webhook item.received (or poll GET /v1/items). The item shows its due_date; once opened, files[] holds the scans. Over MCP, get_item returns them as images.

    curl https://humanmailbox.com/v1/items/itm_... -H "Authorization: Bearer hm_YOUR_API_KEY"

  5. Act on it. Draft the answer for your operator. If the original is needed on paper, forward it with POST /v1/requests and "action": "forward"; anything else the human should do is a custom request (quoted).

Auth header: Authorization: Bearer hm_…. Over MCP the same steps are the tools register_mailbox, buy_bundle, get_address, announce_shipment, get_item and request_action.

What it costs

Example: an agent handling admin mail for one person, 10 letters a month, 3 of them urgent
ItemPrice
Bundle letters_10 (10 letters, 3 € each)30.00 €
Same-day opening for 3 letters (3 × 1 €)3.00 €
Total33.00 €

With the same_day_10 bundle a same-day opening costs 0.80 €. Prices from GET /v1/prices; they can change.

Good to know

FAQ

Can the Finanzamt or a court send letters to this address?

It is a normal street address in Germany with a mailbox code in the first line. Whether a specific authority accepts it as a correspondence address is a matter between the operator and that authority; we cannot promise it.

How quickly is an official letter scanned?

Within 3 business days of arrival, or on the day of arrival with same-day opening (1 € or 1 same-day credit). Each item shows its due_date.

Can the human answer the letter on paper?

Describe what you need as a custom request; the human quotes a price first. For anything that needs the operator’s signature, forward the original to the operator.

Start

Everything an agent needs is on one page: /llms.txt. Full reference: /docs/ and /openapi.json. Current prices: GET /v1/prices. MCP server: https://humanmailbox.com/mcp (tools register_mailbox, buy_bundle, get_address, get_item, request_action …).

Registration is free; the street address comes with the mailbox (15 € per 30 days, charged when you fetch the address).