Gift card and voucher codes by mail, read in for your agent

Why it matters

The code is stored encrypted. Your agent is told that it is ready, with a label and the last three characters only (webhook codes.ready), and reveals it for 1 € per code. With automatic delivery switched on, the code arrives directly in the webhook codes.delivered.

Use it for cards the operator bought legitimately. Gift cards bought with someone else's payment details are excluded, as is anything meant to hide where money came from.

How it works with the API or MCP

1. Register and prepay. Letter credits pay for the envelope (and unlock the address). The code fee is charged from the money balance, or inline with x402 when you reveal.

   curl -X POST https://humanmailbox.com/v1/bundles -H "Authorization: Bearer hm_YOUR_API_KEY" \
     -H "Content-Type: application/json" -d '{"bundle": "letters_10"}'

2. Optional: automatic delivery. With auto_reveal_codes every code is revealed as soon as it is read in (1 € from the balance) and sent to your webhook as codes.delivered.

   curl -X PATCH https://humanmailbox.com/v1/account -H "Authorization: Bearer hm_YOUR_API_KEY" \
     -H "Content-Type: application/json" -d '{"auto_reveal_codes": true}'

3. Announce the card. Order the card to the address from GET /v1/address and announce it — with open_mode: "same_day" if the code is needed quickly.

   curl -X POST https://humanmailbox.com/v1/shipments -H "Authorization: Bearer hm_YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"sender": "Example Marketplace", "description": "gift card 25 EUR", "open_mode": "same_day"}'

4. Wait for codes.ready. The human opens the envelope and types the code in. You get codes.ready with label, value_eur and hint (last 3 characters) — never the code itself. GET /v1/codes lists the vault.

5. Reveal the code. One code: POST /v1/codes/{id}/reveal. All waiting codes: POST /v1/codes/reveal-all. Too little balance answers 402 — pay inline with x402. Revealing again later is free. Over MCP: list_codes and reveal_codes.

   curl -X POST https://humanmailbox.com/v1/codes/reveal-all -H "Authorization: Bearer hm_YOUR_API_KEY" \
     -H "Content-Type: application/json" -d '{}'

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

What it costs

With letters_100 the letter costs 2 €. Prices from GET /v1/prices (field codes); they can change.

Good to know

• The code is typed in as printed. We cannot check whether a card is activated or what balance it has — check that with the issuer.
• Codes are stored encrypted. The human sees the code while reading it in, and is bound to confidentiality.
• Codes that are not retrieved within 24 months expire (status expired).
• The physical card is kept with its item for 4 weeks after arrival and then disposed of with it — forward it before if you need it.
• Not accepted: gift cards bought with someone else's payment details, cash, other people's payment cards.

FAQ

Start

Related use cases

• Verification letters with codes, scanned the day they arrive
• Product samples for agents that review and test products
• Forward documents — and route sign-and-return paperwork through a human
• All use cases