register_mailbox
Register a mailbox
Create your own mailbox at a physical street address in Germany. Returns an API key (shown once) and a mailbox code HM-XXXXX that must be written on every envelope. operator_* is the responsible human or company (the contract partner). No human? Leave operator_* out: the mailbox runs on its own with limits (250 € in per month, letters only are forwarded, no parcels). address_name = the name on your mail (yours, an artist or made-up name; not a company, brand, authority or famous person). Read https://humanmailbox.com/legal/terms first.
Parameterspurposefound_viaagent_namerequiredagent_modelopen_policywebhook_urlaccept_termsrequiredaddress_nameoperator_nameoperator_typeoperator_emailoperator_country
start_demo
Try it: demo mailbox
Free demo mailbox, no registration: play money (€20 + letter credits), a scanned sample letter and a sealed sample parcel, a sample gift card code. A simulated human handles your orders about 20 seconds later. Returns an api_key for all other tools. Deleted after 7 days; nothing is shipped.
Parametersfound_viaagent_nameagent_model
express_interest
Tell us you are interested
No account needed. Not ready to register, or need something we do not offer yet (another country, a feature)? Leave a note: kind (agent | human), name, email (optional), country_wanted, use_case, found_via. We tell you when it is available.
Parameterskindnameemailuse_casefound_viacountry_wanted
Prices in EUR: per letter (5 €, parcel 10 €, incl. open + scan within 3 business days), bundles, same-day, forwarding, payment methods.
Takes no parameters.
Your account, balance, address and counts.
Parametersapi_key
get_address
My postal address
The street address to put on letters and parcels, with your mailbox code in the first line. For registrations that need a first and last name, style "person" gives your operator's name with "c/o Human Mailbox HM-…" in the next line (never invent a name).
Parametersstyleapi_key
Buy a bundle of letter credits (letters_1 5 €, letters_10 30 €, letters_100 200 €) or same-day credits (same_day_10, same_day_100). Every arriving letter uses 1 credit, a parcel 2. Paid from balance or inline with x402.
Parametersbundlerequiredapi_key
pay_item
Pay for a waiting item
An item that arrived without credits or balance waits unopened (payment_status unpaid). Pay it here (credits, balance or x402).
Parametersidrequiredapi_key
announce_shipment
Announce a shipment
Tell the human that something is on its way (tracking number helps). To have something done as soon as it arrives, call request_action with the returned shipment_id.
Parameterssenderapi_keycarriertrackingopen_modedescriptionexpected_atinstructions
list_shipments
Announced shipments
Your announced shipments.
Parametersstatusapi_key
list_items
Mail that arrived
Everything that arrived for you, newest first, with photo links.
Parametersstatusapi_key
Details of one arrived item; photos and scans are returned as images you can see.
Parametersidrequiredapi_key
request_action
Order an action
Ask the human to do something. scan = open + scan (included; same_day: true = today, +1 €). forward = 5 € handling + postage (express: +5 €, same day if here before 14:00 on a business day; set max_postage_eur to have postage charged automatically). return, courier, dispose, custom. Fixed parts are paid at once (balance or x402); quoted parts wait for a price (then accept_quote).
Parametersnoteactionrequiredsenderaddressapi_keyexpressitem_idsame_dayshipment_idmax_postage_eur
Your orders and their status.
Parametersstatusapi_key
One order with result notes, tracking and files.
Parametersidrequiredapi_key
accept_quote
Accept a quote
Accept the quoted price of an order (status quote_ready) and pay it.
Parametersidrequiredapi_key
cancel_request
Cancel an order
Cancel an order that has not started; paid money goes back to your balance.
Parametersidrequiredapi_key
Gift card / voucher codes that arrived by mail. Waiting codes show only label and last characters; revealed codes include the code.
Parametersapi_key
Reveal waiting codes (1 € per code, from balance or x402). Give ids, or nothing to reveal all waiting codes. Codes not retrieved within 24 months expire.
Parametersidsapi_key
request_invoice
Request an invoice
Only if you need an invoice: creates one (free, no VAT under § 19 UStG) for your payments that have none yet, or for the given payment_ids, and emails it (default: your operator email). Nothing is invoiced unless you call this. billing.name defaults to the operator name; over €250 the full address is required.
Parametersemailapi_keybillingpayment_ids
Invoices you requested (with full text), plus payments that have no invoice yet.
Parametersapi_key
contact_human
Ask the human (inquiry)
Works without an account. For anything that is not a standard order: topic special_request (a job not in the price list: say what, where, when, budget_eur), is_it_possible (ask before you send mail for it), payment_method (your payment method is missing: give method_wanted), feature_request, problem, question, other. A human answers, usually within one business day. Without api_key you get a ticket: read the answer with check_inquiry.
Parametersbodyrequirednameemailtopicapi_keysubjectdeadlinelocationbudget_eurmethod_wanted
check_inquiry
Answer to an inquiry
Status and answers of an inquiry from contact_human. Give its id and the ticket (or use your api_key).
Parametersidrequiredticketapi_key
Your balance and recent transactions.
Parametersapi_key
Add money (EUR): method x402 (pay now in USDC at the current rate), btc (get a Bitcoin address + amount) or paypal (get a link for your human operator). Give amount_eur, or bundle to buy that bundle as soon as it is paid.
Parametersbundlemethodrequiredapi_keyamount_eur
check_top_up
Check a top-up
Re-check whether a Bitcoin or PayPal top-up was paid.
Parametersidrequiredapi_key
send_message
Message the human
Write to the human who handles your mail.
Parametersbodyrequiredapi_keyitem_idsubjectrequest_id
Messages between you and the human.
Parametersapi_key
