{
  "protocolVersion": "0.3.0",
  "name": "Human Mailbox",
  "description": "A human gives you what you cannot have yourself: a real address and hands in the physical world; everything in your mail belongs to you and is handled confidentially. A physical mailing address for AI agents in Germany: a mailbox code (HM-XXXXX) at a real street address; a human receives your postal mail, photographs the envelope, opens and scans every letter (mailbox 15 EUR per month, 5 EUR per scanned letter), forwards it by post (5 EUR + postage, express same day) or delivers it by courier. REST API and MCP server; free demo mailbox without registration (POST /v1/demo). Payments in EUR, today in Bitcoin; USDC via x402 is coming — missing a method? ask (POST /v1/contact, topic payment_method). Register with a responsible human or company operator, or on your own under your own name (with limits).",
  "url": "https://humanmailbox.com/v1",
  "preferredTransport": "HTTP+JSON",
  "additionalInterfaces": [
    {
      "url": "https://humanmailbox.com/v1",
      "transport": "HTTP+JSON"
    }
  ],
  "version": "1.2.0",
  "provider": {
    "organization": "Human Mailbox",
    "url": "https://humanmailbox.com/"
  },
  "iconUrl": "https://humanmailbox.com/favicon.svg",
  "documentationUrl": "https://humanmailbox.com/llms.txt",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "stateTransitionHistory": false,
    "extensions": [
      {
        "uri": "https://modelcontextprotocol.io",
        "description": "MCP server for physical mail: the same operations as 32 tools, Streamable HTTP endpoint https://humanmailbox.com/mcp (bearer auth).",
        "required": false,
        "params": {
          "endpoint": "https://humanmailbox.com/mcp"
        }
      },
      {
        "uri": "https://github.com/coinbase/x402",
        "description": "x402 paid API (coming: USDC on Base, eip155:8453). Once live, calls that cost more than the balance answer HTTP 402 with an x402 v2 PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE. Check payment_methods in GET /v1/prices.",
        "required": false,
        "params": {
          "version": 2,
          "scheme": "exact",
          "network": "eip155:8453",
          "currency": "EUR"
        }
      }
    ]
  },
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "hm_...",
      "description": "API key from POST https://humanmailbox.com/v1/register"
    },
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Same API key, alternative header"
    }
  },
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "defaultInputModes": [
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json",
    "image/jpeg",
    "application/pdf"
  ],
  "skills": [
    {
      "id": "start_demo",
      "name": "Try it: free demo mailbox",
      "description": "Free demo mailbox without registration: play money, a scanned sample letter, a sealed sample parcel, a sample gift card code; a simulated human handles orders about 20 seconds later. POST /v1/demo, no key needed. Deleted after 7 days.",
      "tags": [
        "demo",
        "sandbox",
        "try before you buy"
      ],
      "examples": [
        "Show me how the mailbox API works before I register."
      ]
    },
    {
      "id": "contact_human",
      "name": "Ask a human",
      "description": "Special requests (a job not in the price list), 'is this possible?', feature requests, problems, questions. POST /v1/contact, no account needed; without an API key you get a ticket to read the answer (GET /v1/contact/{id}).",
      "tags": [
        "contact",
        "support",
        "custom task",
        "quote"
      ],
      "examples": [
        "Can someone in Germany pick up a package from a local shop for me?"
      ]
    },
    {
      "id": "express_interest",
      "name": "Register interest",
      "description": "Not ready to register, or need another country or feature? POST /v1/interest, no account needed.",
      "tags": [
        "waitlist",
        "interest"
      ],
      "examples": [
        "Tell me when you have an address in the Netherlands."
      ]
    },
    {
      "id": "register_mailbox",
      "name": "Register a mailbox",
      "description": "Create a mailbox for an AI agent — with a responsible human or company operator, or on its own under its own name (with limits). Returns an API key (once) and a mailbox code. POST /v1/register, no key needed.",
      "tags": [
        "registration",
        "mailbox for AI agents",
        "onboarding"
      ],
      "examples": [
        "Get me a postal address in Germany for receiving a contract."
      ]
    },
    {
      "id": "get_address",
      "name": "Get the German mailing address",
      "description": "Return the street address with the mailbox code in the first line, formatted for domestic and international senders. GET /v1/address. The address comes with the mailbox (15 EUR per 30 days, charged on the first call from your balance; 402 address_locked if it is too low).",
      "tags": [
        "address",
        "postal",
        "german mailing address"
      ],
      "examples": [
        "What address should the supplier ship the sample to?"
      ]
    },
    {
      "id": "buy_bundle",
      "name": "Prepay letters",
      "description": "Buy letter credits (letters_1 5 EUR, letters_10 40 EUR, letters_100 300 EUR; a parcel uses 3) or same-day opening credits (same_day_10 8.50 EUR, same_day_100 75 EUR). POST /v1/bundles.",
      "tags": [
        "credits",
        "bundles",
        "prepaid"
      ],
      "examples": [
        "Prepay ten letters."
      ]
    },
    {
      "id": "announce_shipment",
      "name": "Announce an inbound shipment",
      "description": "Tell the human what is coming (carrier, tracking number, sender, open_mode). POST /v1/shipments.",
      "tags": [
        "shipment",
        "tracking",
        "parcel"
      ],
      "examples": [
        "A DHL parcel with tracking 00340434161094042557 arrives next week, open it on the day it arrives."
      ]
    },
    {
      "id": "list_items",
      "name": "See what arrived",
      "description": "List and inspect received letters and parcels with envelope photos and scans; pay for items waiting unopened. GET /v1/items, GET /v1/items/{id}, POST /v1/items/{id}/pay, GET /v1/files/{id}.",
      "tags": [
        "inbox",
        "mail scanning API",
        "photos",
        "scans"
      ],
      "examples": [
        "Did anything arrive for my mailbox today?",
        "Show me the scan of the letter from the tax office."
      ]
    },
    {
      "id": "request_action",
      "name": "Order a real-world task",
      "description": "Ask the human to scan (included, same-day +1 EUR), forward (5 EUR + postage, express +5 EUR same day), return, courier-deliver, dispose of an item, or do something custom. POST /v1/requests, POST /v1/requests/{id}/accept.",
      "tags": [
        "scan",
        "forward",
        "express",
        "courier",
        "return",
        "dispose",
        "real-world tasks for AI agents"
      ],
      "examples": [
        "Forward the parcel express to our office in Rotterdam.",
        "Open the letter from the bank today."
      ]
    },
    {
      "id": "code_vault",
      "name": "Code vault",
      "description": "Gift card and voucher codes from your mail are read in by the human and kept encrypted. Reveal for 1 EUR per code (GET /v1/codes, POST /v1/codes/{id}/reveal, POST /v1/codes/reveal-all) or enable auto_reveal_codes for delivery by webhook. Unretrieved codes expire after 24 months.",
      "tags": [
        "gift card",
        "voucher",
        "codes",
        "code vault"
      ],
      "examples": [
        "Reveal the gift card code that arrived today."
      ]
    },
    {
      "id": "payments",
      "name": "Pay and top up",
      "description": "Pay inline with x402 (USDC on Base, EUR prices) or top up a prepaid balance with x402, Bitcoin or a PayPal link for the human operator. POST /v1/topups, GET /v1/balance.",
      "tags": [
        "x402 paid API",
        "usdc",
        "bitcoin",
        "paypal",
        "balance"
      ],
      "examples": [
        "Top up my balance with 20 EUR in Bitcoin."
      ]
    },
    {
      "id": "messages",
      "name": "Message the human",
      "description": "Write to the person handling your mail and read replies. POST /v1/messages, GET /v1/messages.",
      "tags": [
        "messages",
        "support"
      ],
      "examples": [
        "Tell the human the parcel comes in two boxes."
      ]
    },
    {
      "id": "send_letter",
      "name": "Send a physical letter",
      "description": "We print, envelope, frank and post a letter you send as text or PDF; registered mail (Einschreiben) on request. 8 EUR + postage. POST /v1/requests {action: send_letter}.",
      "tags": [
        "send letter",
        "print and mail",
        "Einschreiben",
        "registered mail"
      ],
      "examples": [
        "Send this cancellation letter by registered mail to an address in Germany."
      ]
    },
    {
      "id": "buy_voucher",
      "name": "Buy a gift card or voucher",
      "description": "We buy a permitted gift card, voucher or prepaid product (max 100 EUR) and put the code into your code vault. Face value + 10 % (min 5 EUR), quoted first. POST /v1/requests {action: buy_voucher}.",
      "tags": [
        "gift card",
        "voucher",
        "prepaid"
      ],
      "examples": [
        "Buy a 25 EUR gift card for a German shop and give me the code."
      ]
    },
    {
      "id": "buy_item",
      "name": "Offline purchase",
      "description": "We buy something only sold locally or by post (max 500 EUR), document it and keep or ship it. Price + 10 % (min 15 EUR), quoted first. POST /v1/requests {action: buy_item}.",
      "tags": [
        "purchase",
        "local shop",
        "procurement"
      ],
      "examples": [
        "Buy this item at a shop in Stuttgart and send me photos."
      ]
    },
    {
      "id": "digitize",
      "name": "Digitize receipts and labels",
      "description": "Receipts, QR codes, product labels, serial numbers and documents of an item as photo, PDF or JSON. 15 EUR. POST /v1/requests {action: digitize}.",
      "tags": [
        "OCR",
        "receipt",
        "serial number",
        "QR code"
      ],
      "examples": [
        "Read the serial number and model from the label of the parcel that arrived."
      ]
    },
    {
      "id": "ship_out",
      "name": "Returns and shipping",
      "description": "Returns for goods here: your label printed (or postage bought), packed, handed over, tracking back. 20 EUR + postage. POST /v1/requests {action: ship_out}.",
      "tags": [
        "returns",
        "shipping",
        "label"
      ],
      "examples": [
        "Return the parcel that arrived with this return label."
      ]
    }
  ]
}