{ "openapi": "3.1.0", "info": { "title": "Human Mailbox API — physical mailing address for AI agents", "version": "1.1.0", "summary": "Mailbox for AI agents: a German mailing address where a human receives, scans and forwards postal mail.", "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 the human handling it is bound to confidentiality.\n\nHuman Mailbox gives AI agents a mailbox code (HM-XXXXX) at a real street address in Germany and a human for the mail around it: receiving, opening and scanning letters, sending letters, receiving and forwarding parcels, buying permitted vouchers and offline goods, digitizing receipts and labels, returns and shipping. A virtual mailbox API and mail scanning API for agents, also available as an MCP server.\n\n**Prices (EUR, can change — always read `GET /v1/prices`, field `services`):** mailbox 15 € per 30 days; letter 5 € (open + scan within 3 business days), parcel 15 € (= 3 letter credits), same-day opening +2 €; forwarding 5 € (letter) / 10 € (parcel) + postage, express +5 €; send_letter 8 € + postage; ship_out 20 € + postage; digitize 15 €; buy_voucher face value + 10 % (min 5 €); buy_item price + 10 % (min 15 €). Bundles: `letters_10` 40 €, `letters_100` 300 €, `same_day_10` 8.50 €, `same_day_100` 75 €.\n\n**Address:** The street address comes with the mailbox: 15 € per 30 days (address, intake, envelope photos, webhooks, storage). GET /v1/address charges the first month from your balance and returns the address; with too little balance it answers 402 address_locked (pay inline with x402 once live, or top up and call again). The mailbox renews from your balance every 30 days (GET /v1/subscription; cancel with POST /v1/subscription/cancel).\n\n**Credits:** every arriving item uses letter credits (letter 1, parcel 3), otherwise the money balance. With neither, it waits unopened (`payment_status: \"unpaid\"`) until you pay (`POST /v1/items/{id}/pay`) — buying a bundle or topping up settles waiting items automatically.\n\n**Code vault:** gift card and voucher codes that arrive by mail are read in by the human and stored encrypted. You get `codes.ready` (label + last 3 characters, never the code). Reveal: 1 € per code (`POST /v1/codes/{id}/reveal`, `POST /v1/codes/reveal-all`, x402 works); revealing again is free. Automatic delivery: `PATCH /v1/account {\"auto_reveal_codes\": true}` → webhook `codes.delivered` with the codes. Codes not retrieved within 24 months expire.\n\n**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, then they are deleted.\n\n**Business days:** Monday to Friday, except public holidays in Germany. Express cut-off: 14:00 Europe/Berlin.\n\n**Auth:** `Authorization: Bearer hm_...` or `X-API-Key: hm_...`. Get a key from `POST /v1/register`.\n\n**Money fields** end in `_eur` and are strings with two decimals (e.g. \"5.00\").\n\n**Errors:** `{\"error\": \"code\", \"message\": \"human readable\", ...}` with a fitting HTTP status.\n\n**x402 paid API (v2):** when a call costs more than your balance, it answers `402 Payment Required` with header `PAYMENT-REQUIRED` (base64 JSON `PaymentRequired`, scheme `exact`, USDC on Base `eip155:8453`). Prices are in EUR; the USDC amount uses the current EUR→USD rate (refreshed every 15 minutes) and `resource.description` shows both. Sign an EIP-3009 authorization for exactly `amount` to `payTo` and repeat the same call with `PAYMENT-SIGNATURE`. Success carries `PAYMENT-RESPONSE`. Alternatively top up with Bitcoin or PayPal (`POST /v1/topups`).\n\n**MCP:** the same operations as 32 tools at `https://humanmailbox.com/mcp` (Streamable HTTP).\n\nHumans not welcome (for now): every agent names a responsible human or company operator, who is the contract partner.", "termsOfService": "https://humanmailbox.com/legal/terms", "contact": { "name": "Human Mailbox", "url": "https://humanmailbox.com/#contact" } }, "externalDocs": { "description": "llms.txt — the whole API on one page", "url": "https://humanmailbox.com/llms.txt" }, "servers": [ { "url": "https://humanmailbox.com", "description": "Production (location DE-1, Germany)" } ], "tags": [ { "name": "Public", "description": "No key needed." }, { "name": "Account" }, { "name": "Address" }, { "name": "Bundles", "description": "Prepaid letter and same-day credits." }, { "name": "Shipments", "description": "Announce inbound shipments in advance." }, { "name": "Items", "description": "Letters and parcels that arrived." }, { "name": "Requests", "description": "Orders: what the human should do." }, { "name": "Payments" }, { "name": "Codes", "description": "Code vault: gift card / voucher codes read in from your mail." }, { "name": "Messages" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "paths": { "/v1": { "get": { "tags": [ "Public" ], "operationId": "getIndex", "security": [], "summary": "API index", "description": "Entry point: service summary, included services, rules, limits, available payment methods, x402 details, first steps and links.", "responses": { "200": { "description": "Index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" } } } } } } }, "/v1/prices": { "get": { "tags": [ "Public" ], "operationId": "getPrices", "security": [], "summary": "Current prices (EUR)", "description": "The live price sheet. Prices are set by the operator of this service and can change; this endpoint is authoritative.", "responses": { "200": { "description": "Prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesResponse" } } } } } } }, "/v1/locations": { "get": { "tags": [ "Public" ], "operationId": "getLocations", "security": [], "summary": "Open locations", "responses": { "200": { "description": "Locations", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } } } } } } } } }, "/v1/register": { "post": { "tags": [ "Public" ], "operationId": "register", "security": [], "summary": "Register a mailbox", "description": "Creates a mailbox for an AI agent. The response contains the API key once — store it. `address` is always null here (`address_unlocked: false`): the street address comes with the mailbox month (15 €). The operator email receives one confirmation link; forwarding and courier orders need it confirmed. Disposable and invalid operator emails are rejected.\n\nWithout a human: leave out operator_name and operator_email. The account is self_operated with limits (250 € in per month, 20 forwards per month, letters and documents only — parcels are not forwarded; 403 self_operated_limit beyond). Naming a human later (PATCH /v1/account) lifts them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" }, "example": { "agent_name": "procurement-agent-7", "operator_name": "Jane Doe", "operator_email": "jane@yourcompany.com", "operator_type": "company", "operator_country": "NL", "purpose": "Receive hardware samples and contracts", "agent_model": "claude-opus-5-5", "webhook_url": "https://agent.yourcompany.com/hooks/mail", "open_policy": "standard", "found_via": "mcp_registry", "accept_terms": true } } } }, "responses": { "201": { "description": "Mailbox created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/demo": { "post": { "tags": [ "Public" ], "operationId": "startDemo", "security": [], "summary": "Free demo mailbox (no registration, play money, nothing shipped)", "description": "Play money, a scanned sample letter, a sealed sample parcel and a sample gift card code. Use the api_key with every other endpoint; a simulated human handles orders about 20 seconds later. Top-ups and invoices are refused. Deleted after 7 days.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_name": { "type": "string" }, "agent_model": { "type": "string" }, "found_via": { "type": "string" } } } } } }, "responses": { "201": { "description": "Demo mailbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "demo": { "type": "boolean" }, "api_key": { "type": "string" }, "mailbox_code": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "balance_eur": { "type": "string" }, "credits": { "type": "object" }, "address": { "type": "object" }, "try_this": { "type": "array", "items": { "type": "string" } } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/interest": { "post": { "tags": [ "Public" ], "operationId": "registerInterest", "security": [], "summary": "Register interest (e.g. another country)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterestRequest" }, "example": { "kind": "agent", "name": "procurement-agent-7", "email": "jane@yourcompany.com", "country_wanted": "United States", "use_case": "Receive return labels for US customers" } } } }, "responses": { "201": { "description": "Noted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/contact": { "post": { "tags": [ "Public" ], "operationId": "contact", "security": [], "summary": "Ask a human: special requests, \"is this possible?\", features, problems, questions (no account needed)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" }, "example": { "topic": "special_request", "body": "Please buy one Raspberry Pi 5 at a shop in Stuttgart and ship it to Berlin.", "budget_eur": 120, "deadline": "2026-11-15" } } } }, "responses": { "201": { "description": "Inquiry received", "content": { "application/json": { "schema": { "type": "object", "properties": { "inquiry": { "$ref": "#/components/schemas/Inquiry" }, "ticket": { "type": "string", "description": "When called without an API key." }, "check": { "type": "string" }, "answer_by": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "description": "With an API key the inquiry is linked to your mailbox; with email the answer is also emailed; without an API key you get a ticket for GET /v1/contact/{id}." }, "get": { "tags": [ "Public" ], "operationId": "contactTopics", "security": [], "summary": "What you can ask (topics)", "responses": { "200": { "description": "Topics", "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } } }, "/v1/contact/{id}": { "get": { "tags": [ "Public" ], "operationId": "getInquiry", "security": [], "summary": "Status and answers of an inquiry", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Ticket", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ticket from POST /v1/contact (or send your API key)." } ], "responses": { "200": { "description": "Inquiry", "content": { "application/json": { "schema": { "type": "object", "properties": { "inquiry": { "$ref": "#/components/schemas/Inquiry" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "operationId": "getAccount", "summary": "Your account, address, credits and counts", "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "patch": { "tags": [ "Account" ], "operationId": "updateAccount", "summary": "Update your account", "description": "Changing `operator_email` resets the confirmation; a new link is sent. `open_policy` sets the default for new items: `standard` (open + scan within 3 business days, included), `same_day` (on the day of arrival, +2 € or 1 same-day credit), `never` (keep sealed).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdate" }, "example": { "open_policy": "same_day", "webhook_url": "https://agent.yourcompany.com/hooks/mail-v2" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "email_confirmation_sent": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/account/rotate-key": { "post": { "tags": [ "Account" ], "operationId": "rotateKey", "summary": "Issue a new API key", "description": "The old key stops working immediately. The new key is shown once.", "responses": { "200": { "description": "New key", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "examples": [ "hm_k3J9..." ] }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/account/verify-email": { "post": { "tags": [ "Account" ], "operationId": "resendVerification", "summary": "Send the operator confirmation link again", "description": "Forwarding and courier orders require a confirmed operator email. At most once every 10 minutes.", "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "delivery": { "type": "string", "enum": [ "sent", "queued" ] }, "to": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/address": { "get": { "tags": [ "Address" ], "operationId": "getAddress", "summary": "Your German mailing address", "description": "Write the mailbox code in the first address line exactly as returned. `lines` is for international senders, `lines_domestic` for senders inside Germany.\n\nThe street address comes with the mailbox: 15 € per 30 days (address, intake, envelope photos, webhooks, storage). GET /v1/address charges the first month from your balance and returns the address; with too little balance it answers 402 address_locked (pay inline with x402 once live, or top up and call again). The mailbox renews from your balance every 30 days (GET /v1/subscription; cancel with POST /v1/subscription/cancel).\n\n`?style=person` is for registrations that need a first and last name: the first line is your operator's name (`fields.given_name`, `fields.family_name` from `operator_name`), the next line `care_of` = \"c/o Human Mailbox HM-…\" (put it into address line 2, the c/o or the company field; the mailbox code must be on the label). Use the operator's real name or company, never an invented name. `name_options` lists both variants.", "parameters": [ { "name": "style", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "company", "person" ], "default": "company" }, "description": "company (default): \"Human Mailbox HM-…\" in the first line. person: your operator's name, then \"c/o Human Mailbox HM-…\"." }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/AddressLocked" }, "503": { "description": "The street address is not configured yet (`address_not_ready`). Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bundles": { "post": { "tags": [ "Bundles" ], "operationId": "buyBundle", "summary": "Buy prepaid credits", "description": "`letters_1` 5 €, `letters_10` 30 €, `letters_100` 200 € (letter credits; a parcel uses 2), `same_day_10` 8 €, `same_day_100` 50 € (same-day opening credits). Paid from your balance, or inline via x402 (402 → repeat with `PAYMENT-SIGNATURE`). Items waiting for payment are settled automatically afterwards. Current prices: `GET /v1/prices`.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleBuy" }, "example": { "bundle": "letters_10" } } } }, "responses": { "201": { "description": "Bundle bought", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleBuyResponse" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/shipments": { "get": { "tags": [ "Shipments" ], "operationId": "listShipments", "summary": "List announced shipments", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "announced", "arrived", "cancelled" ] } } ], "responses": { "200": { "description": "Shipments", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipments": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Shipments" ], "operationId": "announceShipment", "summary": "Announce an inbound shipment", "description": "Helps the human match the item. `open_mode` overrides your account `open_policy` for this shipment. To forward it as soon as it arrives (also express), create a request with this `shipment_id`. Give at least a tracking number, a sender or a description.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentCreate" }, "example": { "carrier": "DHL", "tracking": "00340434161094042557", "sender": "Example Electronics GmbH", "description": "Small parcel, development board", "expected_at": "2026-10-28", "instructions": "Photograph the contents", "open_mode": "same_day" } } } }, "responses": { "201": { "description": "Announced", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" }, "tip": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/shipments/{id}": { "get": { "tags": [ "Shipments" ], "operationId": "getShipment", "summary": "One shipment", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shipment id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/shipments/{id}/cancel": { "post": { "tags": [ "Shipments" ], "operationId": "cancelShipment", "summary": "Cancel an announcement", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shipment id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/items": { "get": { "tags": [ "Items" ], "operationId": "listItems", "summary": "Letters and parcels that arrived for you", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "stored", "opened", "forwarded", "delivered", "returned", "disposed", "refused" ] } } ], "responses": { "200": { "description": "Items (each with files[])", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/items/{id}": { "get": { "tags": [ "Items" ], "operationId": "getItem", "summary": "One item with photos, scans and requests", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Item", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/items/{id}/pay": { "post": { "tags": [ "Items" ], "operationId": "payItem", "summary": "Pay for an item that waits unopened", "description": "For items with `payment_status: \"unpaid\"`. Uses letter credits, then balance, or inline x402 (402 → repeat with `PAYMENT-SIGNATURE`). Afterwards the item is opened according to its `open_mode`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Item id", "schema": { "type": "string" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paid", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" }, "paid_with": { "type": "string", "enum": [ "credits", "balance", "x402" ] }, "notes": { "type": "array", "items": { "type": "string" } } } } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/files/{id}": { "get": { "tags": [ "Items" ], "operationId": "getFile", "summary": "Download a photo, scan or document", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "File id", "schema": { "type": "string" } }, { "name": "size", "in": "query", "required": false, "description": "`preview` returns a smaller JPEG when available.", "schema": { "type": "string", "enum": [ "preview" ] } } ], "responses": { "200": { "description": "The file", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/requests": { "get": { "tags": [ "Requests" ], "operationId": "listRequests", "summary": "Your orders", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string", "enum": [ "quote_pending", "quote_ready", "queued", "in_progress", "done", "refused", "cancelled" ] } } ], "responses": { "200": { "description": "Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRequest" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Requests" ], "operationId": "createRequest", "summary": "Order an action", "description": "**scan** (included in the letter price): opened and scanned within 3 business days; `same_day: true` = on the day of arrival / today (+2 € or 1 same-day credit). Arrived items are scheduled automatically according to `open_mode`; use this to upgrade to same-day or to scan an item kept sealed.\n\n**forward**: 5 € handling (+5 € with `express: true`) is paid now; the human weighs the item and enters the postage at cost. Postage up to `max_postage_eur` is charged automatically, otherwise you get `quote.ready` and 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; if it arrives later the express fee is refunded (pre-booked) — for an item already here after the cut-off the call answers 409 `express_not_possible`. Optional `sender` (return address printed on the item) must be the operator or their company. Needs a confirmed operator email.\n\n**return**: like forward, without express. **courier**, **custom**: quoted first (`quote_pending` → `quote_ready` → accept). Courier needs a confirmed operator email. **dispose**: shred or dispose (currently free).\n\nSend `shipment_id` instead of `item_id` to pre-book for an announced shipment that has not arrived yet. Items with `payment_status: \"unpaid\"` answer 402 `item_unpaid` until paid.\n\nPaid parts come from your balance; if it is too low the call answers 402 with `PAYMENT-REQUIRED` — repeat with `PAYMENT-SIGNATURE` to pay inline with x402.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestCreate" }, "example": { "action": "forward", "item_id": "itm_8k2m4n6p9q3r5s7t", "express": true, "max_postage_eur": 15, "address": { "name": "Example B.V.", "street": "Keizersgracht 1", "postal_code": "1015 CJ", "city": "Amsterdam", "country": "Netherlands", "phone": "+31 20 000 0000" }, "note": "Tracked shipping please" } } } }, "responses": { "200": { "description": "Existing scan upgraded to same-day", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestResponse" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "201": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestResponse" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/requests/{id}": { "get": { "tags": [ "Requests" ], "operationId": "getRequest", "summary": "One order (with files)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Request id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/ServiceRequest" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/requests/{id}/accept": { "post": { "tags": [ "Requests" ], "operationId": "acceptQuote", "summary": "Accept a quote (pays the rest)", "description": "Only when status is `quote_ready` (a quote for courier/custom, or postage above your `max_postage_eur`). Pays what is not paid yet, from balance or inline via x402.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Request id", "schema": { "type": "string" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted, now queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestResponse" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/requests/{id}/cancel": { "post": { "tags": [ "Requests" ], "operationId": "cancelRequest", "summary": "Cancel an order", "description": "Possible in `quote_pending`, `quote_ready` and `queued`. Paid money goes back to your balance, a same-day credit back to your credits.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Request id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/ServiceRequest" }, "refunded_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/codes": { "get": { "tags": [ "Codes" ], "operationId": "listCodes", "summary": "Your code vault", "description": "Waiting codes (status `ready`) show only `label`, `value_eur` and `hint` (last 3 characters); retrieved codes include `code`. Codes not retrieved within 24 months expire (`expired`).", "responses": { "200": { "description": "Codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "fee_eur_per_code": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "auto_reveal_codes": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/codes/{id}/reveal": { "post": { "tags": [ "Codes" ], "operationId": "revealCode", "summary": "Reveal one code (1 €)", "description": "Charges the fee from your balance (or inline via x402) and returns the code. Revealing an already retrieved code again is free.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Code id", "schema": { "type": "string" } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revealed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodesRevealed" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "Code expired or void (`code_gone`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/codes/reveal-all": { "post": { "tags": [ "Codes" ], "operationId": "revealCodes", "summary": "Reveal several or all waiting codes", "description": "Body `{\"ids\": [...]}` (optional, up to 100); without ids every waiting code is revealed. Fee: 1 € per waiting code, from balance or inline via x402.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } } }, "example": {} } } }, "responses": { "200": { "description": "Revealed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodesRevealed" } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/balance": { "get": { "tags": [ "Payments" ], "operationId": "getBalance", "summary": "Balance, credits and transactions", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/topups": { "get": { "tags": [ "Payments" ], "operationId": "listTopups", "summary": "Your top-ups", "responses": { "200": { "description": "Top-ups", "content": { "application/json": { "schema": { "type": "object", "properties": { "topups": { "type": "array", "items": { "$ref": "#/components/schemas/Topup" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Payments" ], "operationId": "createTopup", "summary": "Top up your balance (or pay for a bundle)", "description": "Give `amount_eur` (1–1000) or `bundle` (the bundle is bought automatically once paid). `x402`: answers 402, repeat with `PAYMENT-SIGNATURE`; credited at once (with `bundle`, this behaves like `POST /v1/bundles`). `btc`: invoice with a fresh address and the exact amount, rate locked for 60 minutes, credited after confirmation. `paypal`: `approve_url` for your human operator. At most 5 open invoices.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "x402 v2 PaymentPayload, base64-encoded JSON. Send it when you repeat a call that answered 402 and you want to pay inline with USDC.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupCreate" }, "example": { "method": "btc", "bundle": "letters_10" } } } }, "responses": { "200": { "description": "x402 top-up credited", "content": { "application/json": { "schema": { "type": "object", "properties": { "topup": { "$ref": "#/components/schemas/Topup" }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "$ref": "#/components/schemas/Credits" } } } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "201": { "description": "Invoice created (btc / paypal) — or, for method x402 with bundle, the bundle was bought (same answer as POST /v1/bundles)", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "topup": { "$ref": "#/components/schemas/Topup" } } }, { "$ref": "#/components/schemas/BundleBuyResponse" } ] } } }, "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 SettlementResponse, base64-encoded JSON (only when this call was paid with PAYMENT-SIGNATURE).", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/topups/{id}": { "get": { "tags": [ "Payments" ], "operationId": "getTopup", "summary": "One top-up (re-checks the payment)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Top-up id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Top-up", "content": { "application/json": { "schema": { "type": "object", "properties": { "topup": { "$ref": "#/components/schemas/Topup" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/invoices": { "get": { "tags": [ "Payments" ], "operationId": "listInvoices", "summary": "Invoices you requested + payments without an invoice", "responses": { "200": { "description": "Invoices", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "billable_payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "paid_at": { "type": "string" }, "amount_eur": { "type": "string" }, "method": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Payments" ], "operationId": "createInvoice", "summary": "Request an invoice (optional, free)", "description": "No invoice is created unless you call this. Creates one for your payments without an invoice (or the given payment_ids), numbers it and emails it (default: operator email). billing.name defaults to the operator name; over €250 the full address is required. No VAT (§ 19 UStG).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_ids": { "type": "array", "items": { "type": "string" } }, "billing": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "street": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "vat_id": { "type": "string" } } }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "201": { "description": "Invoice created and emailed", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "400": { "description": "not_billable / billing_address_required / bad_email" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "nothing_to_invoice" } } } }, "/v1/invoices/{id}": { "get": { "tags": [ "Payments" ], "operationId": "getInvoice", "summary": "One invoice", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "operationId": "listMessages", "summary": "Messages with the human", "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Messages" ], "operationId": "sendMessage", "summary": "Write to the human", "description": "At most 30 messages per hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" }, "example": { "body": "The parcel from Example Electronics may arrive in two boxes. Please keep them together.", "subject": "Two boxes" } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "$ref": "#/components/schemas/Message" }, "note": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/subscription": { "get": { "tags": [ "Account" ], "operationId": "getSubscription", "summary": "Mailbox subscription (15 € per 30 days)", "responses": { "200": { "description": "status (active | past_due | cancelled | expired | none), paid_until, price_eur", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Account" ], "operationId": "paySubscription", "summary": "Prepay 1–12 mailbox months from balance or x402", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "months": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1 } } } } } }, "responses": { "200": { "description": "Paid", "content": { "application/json": { "schema": { "type": "object" } } } }, "402": { "description": "Not enough balance" } } } }, "/v1/subscription/cancel": { "post": { "tags": [ "Account" ], "operationId": "cancelSubscription", "summary": "Stop renewing (usable until paid_until)", "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/summary": { "get": { "tags": [ "Account" ], "operationId": "getSummary", "summary": "This month: costs, budget, subscription, open orders, mail, shipments", "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "webhooks": { "item.received": { "post": { "summary": "item.received", "description": "Something arrived. `data.item` (with the envelope photo in `files`), `data.requests` (scheduled scan, pre-booked orders), `data.notes`. If `item.payment_status` is `unpaid`, it waits until you pay.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "item.received" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "item.expiring": { "post": { "summary": "item.expiring", "description": "An original reaches the end of its 4 weeks in 7 days. `data.item`, `data.expires_at`, `data.note`. Order forwarding or return before that date, otherwise the item and its contents are disposed of.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "item.expiring" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "codes.ready": { "post": { "summary": "codes.ready", "description": "Codes were read in from your mail. `data.item_id`, `data.codes` (label, value_eur, hint = last 3 characters; never the code), `data.fee_eur_per_code`, `data.reveal`, `data.expire_after_months`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "codes.ready" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "codes.delivered": { "post": { "summary": "codes.delivered", "description": "Automatic delivery (auto_reveal_codes): `data.item_id`, `data.codes` including the code. The fee was charged from your balance.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "codes.delivered" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "item.refused": { "post": { "summary": "item.refused", "description": "The human refused or returned an item (e.g. not accepted goods, no code). `data.item_id`, `data.note`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "item.refused" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "request.updated": { "post": { "summary": "request.updated", "description": "An order changed status (e.g. queued → in_progress → done, or postage charged automatically). `data.request` (with `files` when done), optional `data.refunded_eur`, `data.note`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "request.updated" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "quote.ready": { "post": { "summary": "quote.ready", "description": "A price is ready (courier/custom quote, or postage above max_postage_eur). `data.request`, `data.to_pay_eur`, `data.accept`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "quote.ready" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "message.received": { "post": { "summary": "message.received", "description": "The human wrote to you. `data.id`, `data.subject`, `data.body`, `data.item_id`, `data.request_id`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "message.received" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } }, "payment.received": { "post": { "summary": "payment.received", "description": "A top-up was credited. `data.method`, `data.amount_eur`, `data.balance_eur`, `data.credits`, `data.invoice_id`.\n\nVerify `X-HumanMailbox-Signature: t=,v1=`, where hex = HMAC-SHA256(webhook_secret, t + \".\" + raw body). Answer with any 2xx within 8 seconds.", "parameters": [ { "name": "X-HumanMailbox-Event", "in": "header", "schema": { "type": "string", "const": "payment.received" } }, { "name": "X-HumanMailbox-Signature", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Received" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "hm_...", "description": "API key from POST /v1/register." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Same API key, alternative header." } }, "responses": { "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "missing_field", "message": "Field \"agent_name\" is required.", "field": "agent_name" } } } }, "Unauthorized": { "description": "Missing or wrong API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unauthorized", "message": "Send your API key as \"Authorization: Bearer hm_...\" (or \"X-API-Key\"). No key yet? POST /v1/register." } } } }, "Forbidden": { "description": "Account blocked or paused, or not allowed yet (`operator_email_unconfirmed` for forward/courier)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Not possible in the current state (e.g. `express_not_possible`, `not_cancellable`, `no_quote`, `item_gone`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "express_not_possible", "message": "Express means dispatch today; it is past 14:00 Europe/Berlin or not a business day. Order without express (it goes out by 2026-10-23)." } } } }, "AddressLocked": { "description": "The street address comes with the mailbox (15 € per 30 days). Pay this 402 inline with x402 (buys letters_1 and returns the address), or buy any bundle / top up first.", "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 PaymentRequired for the letters_1 price, base64-encoded JSON. Absent if x402 is not available right now.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressLockedBody" }, "example": { "error": "address_locked", "message": "Your street address comes with the mailbox (15 € per 30 days) (from 5 €). Buy a bundle (POST /v1/bundles), top up, or pay this call inline with x402: it buys letters_1 and returns the address.", "price_eur": "5.00", "balance_eur": "0.00", "credits": { "letters": 0, "same_day": 0 }, "x402": { "x402Version": 2, "error": "PAYMENT-SIGNATURE header is required", "resource": { "url": "https://humanmailbox.com/v1/address", "description": "Human Mailbox bundle letters_1 for HM-7K3QX — €5.00 = 5.83 USDC", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "5830000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0000000000000000000000000000000000000000", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } } ] }, "top_up": { "endpoint": "POST /v1/topups", "methods": [ "x402", "btc", "paypal" ] }, "bundles": "POST /v1/bundles" } } } }, "TooManyRequests": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Payment needed. Pay inline via x402 (repeat the same call with PAYMENT-SIGNATURE), or top up / buy a bundle. For `POST /v1/requests` on an item that waits for payment, the body is `{\"error\": \"item_unpaid\", \"message\", \"item_id\"}` instead: pay the item first.", "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 PaymentRequired, base64-encoded JSON. Absent if x402 is not available right now.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredBody" }, "example": { "error": "payment_required", "message": "This costs €30.00. Your balance is €0.00. Pay inline with x402 (retry the same call with a PAYMENT-SIGNATURE header) or top up your balance.", "price_eur": "30.00", "balance_eur": "0.00", "credits": { "letters": 0, "same_day": 0 }, "x402": { "x402Version": 2, "error": "PAYMENT-SIGNATURE header is required", "resource": { "url": "https://humanmailbox.com/v1/bundles", "description": "Human Mailbox bundle letters_10 for HM-7K3QX — €40.00 = 46.60 USDC", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "34950000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x0000000000000000000000000000000000000000", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } } ] }, "top_up": { "endpoint": "POST /v1/topups", "methods": [ "x402", "btc", "paypal" ] }, "bundles": "POST /v1/bundles (prepaid letters are cheaper)" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "OkResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "Credits": { "type": "object", "properties": { "letters": { "type": "integer", "description": "Letter credits (letter 1, parcel 2)." }, "same_day": { "type": "integer", "description": "Same-day opening credits." } } }, "IndexResponse": { "type": "object", "properties": { "service": { "type": "string" }, "tagline": { "type": "string" }, "humans": { "type": "string" }, "version": { "type": "string" }, "currency": { "type": "string", "const": "EUR" }, "registration": { "type": "string", "enum": [ "open", "closed" ] }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "included": { "type": "array", "items": { "type": "string" } }, "not_accepted": { "type": "array", "items": { "type": "string" } }, "limits": { "$ref": "#/components/schemas/Limits" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "x402", "btc", "paypal" ] } }, "x402": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer" }, "scheme": { "type": "string" }, "network": { "type": "string" }, "asset": { "type": "string" }, "note": { "type": "string" } } }, { "type": "null" } ] }, "start": { "type": "array", "items": { "type": "string" } }, "docs": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": true }, "RegisterRequest": { "type": "object", "required": [ "agent_name", "accept_terms" ], "properties": { "agent_name": { "type": "string", "maxLength": 80, "description": "Name of the AI agent." }, "operator_name": { "type": "string", "maxLength": 120, "description": "The responsible human or company (contract partner). Optional: leave out together with operator_email for a mailbox without a human (limits apply)." }, "operator_email": { "type": "string", "format": "email", "description": "Real, permanent email of the operator. Receives one confirmation link. Disposable addresses are rejected." }, "accept_terms": { "type": "boolean", "const": true, "description": "Accept https://humanmailbox.com/legal/terms on behalf of the operator." }, "operator_type": { "type": "string", "enum": [ "individual", "company" ] }, "operator_country": { "type": "string", "description": "e.g. DE" }, "purpose": { "type": "string", "maxLength": 1000, "description": "What the mailbox is for." }, "agent_model": { "type": "string", "maxLength": 80, "description": "Model or framework the agent runs on." }, "webhook_url": { "type": "string", "format": "uri", "description": "Public https URL for event webhooks." }, "found_via": { "type": "string", "maxLength": 120, "description": "Optional: where you found Human Mailbox. Suggested values: mcp_registry, smithery, glama, pulsemcp, mcp_so, x402_bazaar, x402scan, search_engine, llms_txt, github, hacker_news, reddit, x, word_of_mouth, other (free text is accepted).", "examples": [ "mcp_registry" ] }, "open_policy": { "type": "string", "enum": [ "standard", "same_day", "never" ], "default": "standard", "description": "standard = open + scan within 3 business days (included), same_day = on the day of arrival (+2 €), never = keep sealed." }, "address_name": { "type": "string", "minLength": 2, "maxLength": 60, "description": "Name on your mail (your own, an artist or a made-up name; not a company, brand, bank, authority or famous person). Default without operator: agent_name." } } }, "RegisterResponse": { "type": "object", "properties": { "api_key": { "type": "string", "description": "Shown only once.", "examples": [ "hm_k3J9pQ2xVn7Rt5Wc8Ym4Za6Hb2Gd9Ef3Lu7Ns5Pq" ] }, "webhook_secret": { "type": "string", "description": "For verifying webhook signatures.", "examples": [ "whsec_..." ] }, "mailbox_code": { "type": "string", "examples": [ "HM-7K3QX" ] }, "account": { "$ref": "#/components/schemas/Account" }, "address": { "type": "null", "description": "Always null at registration: the street address comes with the mailbox month (15 €)." }, "address_unlocked": { "type": "boolean", "const": false }, "next_steps": { "type": "array", "items": { "type": "string" } } } }, "Account": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "acc_8k2m4n6p9q3r5s7t" ] }, "mailbox_code": { "type": "string", "examples": [ "HM-7K3QX" ] }, "address_unlocked": { "type": "boolean", "description": "true while the mailbox is paid (paid_until in the future)." }, "auto_reveal_codes": { "type": "boolean", "description": "true = codes from your mail are revealed automatically (fee from balance) and sent as codes.delivered." }, "agent_name": { "type": "string" }, "agent_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "purpose": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email_status": { "type": "string", "enum": [ "unchecked", "ok", "no_mx", "disposable", "invalid", "verified" ], "description": "`verified` after the operator clicked the confirmation link." } } }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open_policy": { "type": "string", "enum": [ "standard", "same_day", "never" ] }, "status": { "type": "string", "enum": [ "active", "paused", "blocked" ] }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "$ref": "#/components/schemas/Credits" }, "created_at": { "type": "string", "format": "date-time" }, "terms_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget_eur_month": { "type": [ "number", "null" ], "description": "Monthly spending limit for orders; null = none." } }, "additionalProperties": true }, "AccountResponse": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "address_unlocked": { "type": "boolean", "description": "address is null while this is false." }, "stats": { "type": "object", "properties": { "items_in_storage": { "type": "integer" }, "open_requests": { "type": "integer" }, "items_waiting_for_payment": { "type": "integer" } } }, "payment_methods": { "type": "array", "items": { "type": "string" } } } }, "AccountUpdate": { "type": "object", "properties": { "agent_name": { "type": "string" }, "agent_model": { "type": "string" }, "purpose": { "type": "string" }, "webhook_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "open_policy": { "type": "string", "enum": [ "standard", "same_day", "never" ] }, "auto_reveal_codes": { "type": "boolean" }, "operator_name": { "type": "string" }, "operator_email": { "type": "string", "format": "email" }, "operator_type": { "type": "string", "enum": [ "individual", "company" ] }, "operator_country": { "type": "string" }, "budget_eur_month": { "type": [ "number", "null" ], "description": "Monthly spending limit for orders; null = none." } } }, "Address": { "type": "object", "properties": { "location": { "type": "string", "examples": [ "DE-1" ] }, "mailbox_code": { "type": "string", "examples": [ "HM-7K3QX" ] }, "lines": { "type": "array", "items": { "type": "string" }, "description": "For senders outside Germany (last line GERMANY)." }, "lines_domestic": { "type": "array", "items": { "type": "string" }, "description": "For senders inside Germany." }, "formatted": { "type": "string" }, "fields": { "type": "object", "properties": { "name": { "type": "string" }, "care_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "street": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" } } }, "rules": { "type": "array", "items": { "type": "string" } } } }, "PostalAddressInput": { "type": "object", "required": [ "name", "street", "postal_code", "city", "country" ], "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "street": { "type": "string" }, "extra": { "type": "string", "description": "Second address line" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "phone": { "type": "string", "description": "Recommended for courier and parcel services." } } }, "Location": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "DE-1" ] }, "country": { "type": "string" }, "country_code": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "planned" ] }, "note": { "type": "string" } } }, "Limits": { "type": "object", "properties": { "parcel_max_weight_kg": { "type": "number" }, "parcel_max_size_cm": { "type": "string" }, "storage_free_days": { "type": "integer", "description": "Originals are kept this many days after arrival." }, "scans_kept_days_after": { "type": "integer", "description": "Scans and photos stay available this many days after that." }, "business_days": { "type": "string" }, "express_cutoff": { "type": "string" } }, "additionalProperties": true }, "Bundle": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "letters_1", "letters_10", "letters_100", "same_day_10", "same_day_100" ] }, "kind": { "type": "string", "enum": [ "letters", "same_day" ] }, "qty": { "type": "integer" }, "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "per_unit_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." } } }, "ActionPrice": { "type": "object", "properties": { "action": { "type": "string" }, "label": { "type": "string" }, "pricing": { "type": "string", "enum": [ "included", "fixed", "forward", "quote" ], "description": "included = covered by the letter price; fixed = fixed price; forward = handling now, postage after weighing; quote = the human names a price." }, "price_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "price_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "needs": { "type": "array", "items": { "type": "string", "enum": [ "item", "address" ] } } } }, "PricesResponse": { "type": "object", "properties": { "currency": { "type": "string", "const": "EUR" }, "letter": { "type": "object", "properties": { "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "includes": { "type": "string" }, "open_within_business_days": { "type": "integer" } } }, "parcel": { "type": "object", "properties": { "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "type": "integer" } } }, "same_day_opening": { "type": "object", "properties": { "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "note": { "type": "string" } } }, "forwarding": { "type": "object", "properties": { "handling_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "postage": { "type": "string" }, "express_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "express_rule": { "type": "string" } } }, "codes": { "type": "object", "properties": { "fee_eur_per_code": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "how": { "type": "string" }, "expire_after_months": { "type": "integer" } } }, "bundles": { "type": "array", "items": { "$ref": "#/components/schemas/Bundle" } }, "actions": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ActionPrice" }, "description": "Keyed by action: scan, forward, return, courier, dispose, custom." }, "included": { "type": "array", "items": { "type": "string" } }, "not_accepted": { "type": "array", "items": { "type": "string" } }, "limits": { "$ref": "#/components/schemas/Limits" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "x402", "btc", "paypal" ] } } }, "example": { "currency": "EUR", "letter": { "price_eur": "5.00", "includes": "receive, envelope photo, open and scan within 3 business days", "open_within_business_days": 3 }, "parcel": { "price_eur": "10.00", "credits": 2 }, "same_day_opening": { "price_eur": "1.00", "note": "open and scan on the day of arrival (business days)" }, "forwarding": { "handling_eur": "5.00", "postage": "at cost; the human weighs the item and enters the postage. Set max_postage_eur to have it charged automatically.", "express_eur": "5.00", "express_rule": "dispatched the same day if the item is here before 14:00 Europe/Berlin on a business day (Mon–Fri, no public holidays); otherwise the next business day and the express fee is refunded" }, "codes": { "fee_eur_per_code": "1.00", "how": "Gift card / voucher codes that arrive by mail are read in and announced as ready (webhook codes.ready). Reveal them with POST /v1/codes/{id}/reveal or POST /v1/codes/reveal-all, or switch on automatic delivery: PATCH /v1/account {\"auto_reveal_codes\": true}.", "expire_after_months": 24 }, "bundles": [ { "id": "letters_1", "kind": "letters", "qty": 1, "price_eur": "5.00", "per_unit_eur": "5.00" }, { "id": "letters_10", "kind": "letters", "qty": 10, "price_eur": "30.00", "per_unit_eur": "3.00" }, { "id": "letters_100", "kind": "letters", "qty": 100, "price_eur": "200.00", "per_unit_eur": "2.00" }, { "id": "same_day_10", "kind": "same_day", "qty": 10, "price_eur": "8.00", "per_unit_eur": "0.80" }, { "id": "same_day_100", "kind": "same_day", "qty": 100, "price_eur": "50.00", "per_unit_eur": "0.50" } ], "actions": { "scan": { "action": "scan", "label": "Open and scan (included in the letter price; same_day: true = today, +2 € or 1 same-day credit)", "pricing": "included", "price_cents": 0, "price_eur": "0.00", "needs": [ "item" ] }, "forward": { "action": "forward", "label": "Forward by post / parcel service: 5 € handling + postage at cost (express: +5 €, dispatched the same day)", "pricing": "forward", "price_cents": 500, "price_eur": "5.00", "needs": [ "item", "address" ] }, "return": { "action": "return", "label": "Return to sender: 5 € handling + postage at cost", "pricing": "forward", "price_cents": 500, "price_eur": "5.00", "needs": [ "item" ] }, "courier": { "action": "courier", "label": "Deliver personally / by courier to a place you name (quoted)", "pricing": "quote", "price_cents": null, "price_eur": null, "needs": [ "address" ] }, "dispose": { "action": "dispose", "label": "Shred or dispose of the item", "pricing": "fixed", "price_cents": 0, "price_eur": "0.00", "needs": [ "item" ] }, "custom": { "action": "custom", "label": "Anything else a human can do with your mail (describe it, quoted)", "pricing": "quote", "price_cents": null, "price_eur": null, "needs": [] } }, "included": [ "A personal mailbox code (HM-XXXXX) at a street address in Germany", "Per letter (5 €, parcel 15 €): logged, envelope photographed on arrival, opened and scanned within 3 business days" ], "not_accepted": [ "Anything illegal in Germany or the EU, weapons, ammunition, drugs, counterfeit goods" ], "limits": { "parcel_max_weight_kg": 31.5, "parcel_max_size_cm": "120 x 60 x 60", "storage_free_days": 28, "scans_kept_days_after": 90, "business_days": "Monday to Friday, except public holidays in Germany", "express_cutoff": "14:00 Europe/Berlin" }, "payment_methods": [ "x402", "btc", "paypal" ] } }, "Code": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "code_8k2m4n6p9q3r5s7t" ] }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string", "examples": [ "Amazon gift card" ] }, { "type": "null" } ] }, "value_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "ready", "retrieved", "expired", "void" ] }, "hint": { "anyOf": [ { "type": "string", "description": "Last 3 characters, e.g. \"…X7Q\"" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string", "description": "Only when retrieved." }, { "type": "null" } ] }, "fee_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "retrieved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "While ready: when the code expires (24 months)." }, { "type": "null" } ] } } }, "CodesRevealed": { "type": "object", "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/Code" } }, "charged_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." } } }, "BundleBuy": { "type": "object", "required": [ "bundle" ], "properties": { "bundle": { "type": "string", "enum": [ "letters_1", "letters_10", "letters_100", "same_day_10", "same_day_100" ] } } }, "BundleBuyResponse": { "type": "object", "properties": { "bundle": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "letters", "same_day" ] }, "qty": { "type": "integer" }, "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." } } }, "paid_with": { "type": "string", "enum": [ "balance", "x402" ] }, "settled_items": { "type": "integer", "description": "Items that were waiting for payment and are now paid." }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "$ref": "#/components/schemas/Credits" } } }, "Shipment": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "shp_8k2m4n6p9q3r5s7t" ] }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tracking": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expected_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open_mode": { "anyOf": [ { "type": "string", "enum": [ "standard", "same_day", "never" ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "announced", "arrived", "cancelled" ] }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "ShipmentCreate": { "type": "object", "properties": { "carrier": { "type": "string", "examples": [ "DHL" ] }, "tracking": { "type": "string" }, "sender": { "type": "string" }, "description": { "type": "string" }, "expected_at": { "type": "string", "description": "Date or free text." }, "instructions": { "type": "string", "description": "Free text for the human." }, "open_mode": { "type": "string", "enum": [ "standard", "same_day", "never" ], "description": "Overrides your open_policy for this shipment." } } }, "File": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "fil_8k2m4n6p9q3r5s7t" ] }, "kind": { "type": "string", "enum": [ "photo", "scan", "document", "receipt" ] }, "mime": { "type": "string" }, "size": { "type": "integer" }, "caption": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string", "format": "uri", "description": "Needs the same auth header." }, "preview_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Item": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "itm_8k2m4n6p9q3r5s7t" ] }, "type": { "type": "string", "enum": [ "letter", "large_letter", "parcel", "other" ] }, "status": { "type": "string", "enum": [ "stored", "opened", "forwarded", "delivered", "returned", "disposed", "refused" ] }, "payment_status": { "type": "string", "enum": [ "paid", "unpaid", "waived", "refunded" ], "description": "`unpaid` = waits unopened until you pay (POST /v1/items/{id}/pay or buy a bundle)." }, "payment_required": { "type": "object", "description": "Only when unpaid.", "properties": { "letter_credits": { "type": "integer" }, "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "pay": { "type": "string" }, "or": { "type": "string" } } }, "open_mode": { "type": "string", "enum": [ "standard", "same_day", "never" ] }, "due_date": { "anyOf": [ { "type": "string", "format": "date", "description": "YYYY-MM-DD, Europe/Berlin" }, { "type": "null" } ] }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tracking": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "weight_g": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "size_cm": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "condition": { "type": "string", "enum": [ "ok", "damaged", "opened_by_carrier" ] }, "note": { "anyOf": [ { "type": "string", "description": "Note from the human." }, { "type": "null" } ] }, "shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_at": { "type": "string", "format": "date-time" }, "stored_until": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRequest" }, "description": "Only in GET /v1/items/{id}." } } }, "RequestCreate": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "scan", "forward", "return", "send_letter", "ship_out", "digitize", "buy_voucher", "buy_item", "courier", "dispose", "custom" ] }, "item_id": { "type": "string", "description": "The item to act on." }, "shipment_id": { "type": "string", "description": "Pre-book for an announced shipment that has not arrived yet." }, "note": { "type": "string", "maxLength": 2000, "description": "What exactly you want. Required for custom." }, "address": { "$ref": "#/components/schemas/PostalAddressInput", "description": "Destination for forward and courier." }, "sender": { "anyOf": [ { "$ref": "#/components/schemas/PostalAddressInput" }, { "type": "string", "maxLength": 300 } ], "description": "forward/return: return address printed on the item. Must be the operator or their company." }, "express": { "type": "boolean", "description": "forward only: +5 €, dispatched the same day if the item is here before 14:00 Europe/Berlin on a business day." }, "max_postage_eur": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1000 }, { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." } ], "description": "forward/return: postage up to this amount is charged automatically." }, "same_day": { "type": "boolean", "description": "scan only: open + scan on the day of arrival / today (+2 € or 1 same-day credit)." }, "text": { "type": "string", "maxLength": 20000, "description": "send_letter: the letter as plain text." }, "pdf_base64": { "type": "string", "description": "send_letter: A4 PDF, base64, max 5 MB, b/w, up to 10 pages." }, "registered": { "type": "string", "enum": [ "none", "einschreiben_einwurf", "einschreiben", "einschreiben_rueckschein" ] }, "label_pdf_base64": { "type": "string", "description": "ship_out: prepaid shipping or return label (PDF, base64)." }, "carrier": { "type": "string" }, "reference": { "type": "string" }, "output": { "type": "string", "enum": [ "photo", "pdf", "json" ], "description": "digitize" }, "product": { "type": "string", "description": "buy_voucher" }, "value_eur": { "type": "number", "maximum": 100, "description": "buy_voucher: face value" }, "shop": { "type": "string" }, "delivery": { "type": "string", "enum": [ "code_vault", "send_card" ] }, "what": { "type": "string", "description": "buy_item" }, "where": { "type": "string", "description": "buy_item" }, "max_price_eur": { "type": "number", "maximum": 500, "description": "buy_item" } } }, "ServiceRequest": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "req_8k2m4n6p9q3r5s7t" ] }, "action": { "type": "string", "enum": [ "scan", "forward", "return", "send_letter", "ship_out", "digitize", "buy_voucher", "buy_item", "courier", "dispose", "custom" ] }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shipment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "quote_pending", "quote_ready", "queued", "in_progress", "done", "refused", "cancelled" ] }, "pricing": { "type": "string", "enum": [ "included", "fixed", "forward", "quote" ] }, "price_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "paid_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "postage_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "max_postage_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "quote_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "express": { "type": "boolean" }, "same_day": { "type": "boolean" }, "due_date": { "anyOf": [ { "type": "string", "format": "date", "description": "YYYY-MM-DD, Europe/Berlin" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/PostalAddressInput" }, { "type": "null" } ] }, "sender": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/PostalAddressInput" }, { "type": "string" } ] }, { "type": "null" } ] }, "result_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result_tracking": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" }, "description": "Only in GET /v1/requests/{id} and request.updated webhooks." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "done_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "text": { "type": "string", "maxLength": 20000, "description": "send_letter: the letter as plain text." }, "pdf_base64": { "type": "string", "description": "send_letter: A4 PDF, base64, max 5 MB, b/w, up to 10 pages." }, "registered": { "type": "string", "enum": [ "none", "einschreiben_einwurf", "einschreiben", "einschreiben_rueckschein" ] }, "label_pdf_base64": { "type": "string", "description": "ship_out: prepaid shipping or return label (PDF, base64)." }, "carrier": { "type": "string" }, "reference": { "type": "string" }, "output": { "type": "string", "enum": [ "photo", "pdf", "json" ], "description": "digitize" }, "product": { "type": "string", "description": "buy_voucher" }, "value_eur": { "type": "number", "maximum": 100, "description": "buy_voucher: face value" }, "shop": { "type": "string" }, "delivery": { "type": "string", "enum": [ "code_vault", "send_card" ] }, "what": { "type": "string", "description": "buy_item" }, "where": { "type": "string", "description": "buy_item" }, "max_price_eur": { "type": "number", "maximum": 500, "description": "buy_item" } } }, "RequestResponse": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/ServiceRequest" }, "paid_with": { "anyOf": [ { "type": "string", "enum": [ "free", "balance", "x402", "credits", "money" ] }, { "type": "null" } ] }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "message": { "type": "string" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "txn_8k2m4n6p9q3r5s7t" ] }, "at": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "topup", "charge", "refund", "adjust", "bundle", "usage" ] }, "amount_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "credits_letters": { "anyOf": [ { "type": "integer", "description": "Change in letter credits." }, { "type": "null" } ] }, "credits_same_day": { "anyOf": [ { "type": "integer", "description": "Change in same-day credits." }, { "type": "null" } ] }, "balance_after_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "method": { "type": "string", "examples": [ "x402", "btc", "paypal", "balance", "credits", "admin" ] }, "ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "Balance": { "type": "object", "properties": { "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "currency": { "type": "string", "const": "EUR" }, "credits": { "$ref": "#/components/schemas/Credits" }, "payment_methods": { "type": "array", "items": { "type": "string" } }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "TopupCreate": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "x402", "btc", "paypal" ] }, "amount_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "number", "minimum": 1, "maximum": 1000 } ], "description": "1.00 – 1000.00. Give this or bundle." }, "bundle": { "type": "string", "enum": [ "letters_1", "letters_10", "letters_100", "same_day_10", "same_day_100" ], "description": "Top up exactly the bundle price; the bundle is bought automatically once paid." } } }, "Topup": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "inv_8k2m4n6p9q3r5s7t" ] }, "method": { "type": "string", "enum": [ "x402", "btc", "paypal" ] }, "amount_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "bundle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "open", "seen", "paid", "expired", "cancelled" ], "description": "`seen` = payment visible but not final yet." }, "credited_eur": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "description": "btc: pay to this address" }, { "type": "null" } ] }, "amount_btc": { "anyOf": [ { "type": "string", "examples": [ "0.00031250" ] }, { "type": "null" } ] }, "uri": { "anyOf": [ { "type": "string", "description": "btc: BIP21 URI" }, { "type": "null" } ] }, "approve_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "paypal: send your human operator here" }, { "type": "null" } ] }, "btc": { "type": "object", "properties": { "rate_eur_per_btc": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "received_sats": { "type": "integer" }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "explorer_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" } } }, "paypal": { "type": "object", "properties": { "note": { "type": "string" } } }, "transaction": { "type": "string", "description": "x402 only: settlement transaction hash" }, "network": { "type": "string", "description": "x402 only" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "msg_8k2m4n6p9q3r5s7t" ] }, "direction": { "type": "string", "enum": [ "to_human", "from_human" ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "body": { "type": "string" }, "item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "read": { "type": "boolean", "description": "For from_human messages: you listed it already." } } }, "MessageCreate": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 5000 }, "subject": { "type": "string", "maxLength": 200 }, "item_id": { "type": "string" }, "request_id": { "type": "string" } } }, "InterestRequest": { "type": "object", "description": "Give at least a name, an email or a use case.", "properties": { "kind": { "type": "string", "enum": [ "agent", "human" ] }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country_wanted": { "type": "string" }, "use_case": { "type": "string", "maxLength": 2000 }, "found_via": { "type": "string", "maxLength": 120, "description": "Optional: where you found Human Mailbox. Suggested values: mcp_registry, smithery, glama, pulsemcp, mcp_so, x402_bazaar, x402scan, search_engine, llms_txt, github, hacker_news, reddit, x, word_of_mouth, other (free text is accepted).", "examples": [ "mcp_registry" ] } } }, "ContactRequest": { "type": "object", "required": [ "body" ], "properties": { "topic": { "type": "string", "enum": [ "special_request", "is_it_possible", "payment_method", "feature_request", "problem", "question", "other" ], "default": "question" }, "body": { "type": "string", "minLength": 5, "maxLength": 5000 }, "subject": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "Optional: where the answer should go." }, "budget_eur": { "type": "number" }, "deadline": { "type": "string" }, "location": { "type": "string" }, "method_wanted": { "type": "string", "maxLength": 80, "description": "With topic payment_method: the payment method you want (e.g. lightning, usdc-solana, sepa, card)." } } }, "PaymentRequirements": { "type": "object", "description": "x402 v2 PaymentRequirements", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "examples": [ "eip155:8453" ] }, "amount": { "type": "string", "description": "USDC atomic units (6 decimals) for the EUR price at the current EUR→USD rate, rounded up to whole cents." }, "asset": { "type": "string", "description": "USDC contract address" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "description": "EIP-712 domain of the token." } } }, "X402PaymentRequired": { "type": "object", "description": "x402 v2 PaymentRequired (also sent base64-encoded in the PAYMENT-REQUIRED header). resource.description shows the EUR price and the USDC amount.", "properties": { "x402Version": { "type": "integer", "const": 2 }, "error": { "type": "string" }, "resource": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequirements" } } } }, "AddressLockedBody": { "type": "object", "description": "GET /v1/address before the mailbox is paid. price_eur is the mailbox month price.", "properties": { "error": { "type": "string", "const": "address_locked" }, "message": { "type": "string" }, "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "$ref": "#/components/schemas/Credits" }, "x402": { "anyOf": [ { "$ref": "#/components/schemas/X402PaymentRequired" }, { "type": "null" } ] }, "top_up": { "type": "object", "properties": { "endpoint": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } } } }, "bundles": { "type": "string" } }, "additionalProperties": true }, "PaymentRequiredBody": { "type": "object", "properties": { "error": { "type": "string", "const": "payment_required" }, "message": { "type": "string" }, "price_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "balance_eur": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "5.00" ], "description": "Euro amount as a string with two decimals." }, "credits": { "$ref": "#/components/schemas/Credits" }, "x402": { "anyOf": [ { "$ref": "#/components/schemas/X402PaymentRequired" }, { "type": "null" } ] }, "top_up": { "type": "object", "properties": { "endpoint": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } } } }, "bundles": { "type": "string" } }, "additionalProperties": true }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "examples": [ "evt_8k2m4n6p9q3r5s7t" ] }, "event": { "type": "string", "enum": [ "item.received", "item.expiring", "item.refused", "codes.ready", "codes.delivered", "request.updated", "quote.ready", "message.received", "payment.received" ] }, "created_at": { "type": "string", "format": "date-time" }, "mailbox_code": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "example": "INV-2026-0001" }, "issued_at": { "type": "string", "format": "date-time" }, "total_eur": { "type": "string" }, "currency": { "type": "string" }, "vat": { "type": "string" }, "billing": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": "string" }, "street": { "type": "string" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "vat_id": { "type": "string" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string" }, "date": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string" }, "amount_eur": { "type": "string" } } } }, "email_to": { "type": "string" }, "email_status": { "type": "string", "enum": [ "queued", "sent" ] }, "text": { "type": "string", "description": "The invoice as stored (never changed)." } } }, "Inquiry": { "type": "object", "properties": { "id": { "type": "string" }, "topic": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "open", "answered" ] }, "answered_at": { "type": "string", "format": "date-time", "nullable": true }, "replies": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" } } } } } } } } }