You send the addresses. We print and mail a one-time code to each, check every code that comes back, and keep the record. Log in to see who's verified and when, or let your agent get an alert for each address.
Upload a list in the dashboard, or have your agent send it over MCP or the API, with your own id for each address.
A QR code and a short code such as K7D2-M9XQ, unique to that address.
First-Class from our facility in Manhattan Beach, CA, as a postcard or as a letter in an envelope.
Scanned, typed at mailbox.bot/v or typed in your own app, each code is matched to its address once and expires after 30 days.
Log in to see which addresses are verified and when, or let your agent get a webhook alert for each one.
Open Batch mail: each verification batch shows how many addresses are verified, and every address with Verified and the time, or its scans so far. Download it as a CSV report whenever you like.
Your agent subscribes once, over MCP with create_webhook_endpoint or with POST /v1/webhooks/endpoints, and gets batch.piece.confirmed for each verified address, signed and with your id for it. batch.piece.scanned tells it about first scans.
A 4×6 postcard is $1.05 and a one-sheet letter $1.15, printing and First-Class postage included. The codes, the checks, the tracking and the alerts are included.
Mail something to the address that only someone there can read, and ask them to enter it. We print a one-time code on each postcard or letter, mail it, check it the first time it's scanned or typed, and keep the record: you see it as Verified in your dashboard, and your agent can get a webhook alert with your own id for that address. A mailed code shows that someone at the address receives mail there. It doesn't show who they are or that they own the place, so pair it with your own identity checks.
Whichever way the code comes back, the first entry verifies the address: it shows as Verified in your dashboard, and your agent's webhook gets one alert.
Opens a mailbox.bot page with one button, Verify my address. Afterwards the page can send them on to your own link.
For anyone who would rather not scan. The code is printed in large type beside the QR code, with the address to type it at.
Your app sends it to POST /v1/batch-mail/verify with your key and gets the piece and your ref back at once, so your user sees Verified on your own screen.
Each row is who acts: your app or your agent, mailbox.bot, and the person at the address. Follow the line to the outcome.
A new seller signs up. Your app adds them to the day's verification batch with their seller id as the ref; they type the code from the postcard on your verify screen, and your verify call marks them live.
Your agent adds new vendors to a verification batch and you approve the cost. When a vendor scans the code, batch.piece.confirmed reaches the agent's webhook with the vendor's id, and it updates your records.
Someone asks to change the address on an account. Hold the change, mail a code to the new address, and apply it only when the code comes back, so a takeover can't redirect checks, cards or shipments. One postcard is $3.05.
They answer different questions, and most teams use both.
| Check | What it tells you |
|---|---|
| Address validation software | Checks that an address exists and can get mail, against USPS address data.When someone types an address in your form. |
| Mail verification | Shows that someone at the address receives mail there, because they entered a code that only came by mail.Before money, goods or trust move to that address. |
The first entry verifies the address. Entering the code again says it was already verified, and the alert is sent once.
After 30 days by default, or any 1 to 90 days you set, counted from the mail date. An expired code still counts a scan but never verifies.
8 characters from a 31-character alphabet make about 853 billion codes, and typing is limited to 10 tries per network in 10 minutes at mailbox.bot/v and 120 checks a minute per account on the API.
The verify call answers only for your own pieces in the key's environment, and an agent key only for its own batches. Another sender's codes don't exist for you.
A scan stores a count and the times. No IP address and no device details are kept, and link previews and crawlers aren't counted.
A postcard shows its code to anyone who handles it. When that matters, send a letter, from 10 pieces: the code travels inside the envelope.
Over MCP from Claude, ChatGPT, your IDE or your agent harness, the same batch tools take qr.mode verify. A sandbox key (sk_agent_test_) runs it all for free and mails nothing.
POST /api/v1/batch-mail
Authorization: Bearer $MAILBOX_AGENT_KEY
X-Mailbox-MD-Version: 2
Idempotency-Key: sellers-2026-11-03
{
"job_name": "Seller verification, 3 Nov",
"mail_type": "postcard_4x6",
"template_url": "https://example.com/verify-card-front.pdf",
"recipients": [
{ "name": "Rivera Ceramics", "line1": "2214 Pico Blvd", "city": "Santa Monica",
"state": "CA", "zip": "90405", "ref": "seller-48213" }
],
"qr": { "mode": "verify", "url": "https://example.com/verified", "expires_days": 30 }
}POST /api/v1/batch-mail/verify
Authorization: Bearer $MAILBOX_AGENT_KEY
{ "code": "k7d2 m9xq" }
200 OK
{ "verified": true, "already_verified": false, "batch_id": "b5f0…",
"piece": 214, "ref": "seller-48213",
"verified_at": "2026-11-06T15:02:40Z", "sandbox": false }You mail something to the address that only someone there can read, and ask them to enter it. We print a one-time code on each postcard or letter, mail it First-Class, check it the first time it's scanned or typed, and keep the record: it shows as Verified in your dashboard, and your agent can get a webhook alert with your own id for that address.
It shows that someone at the address receives mail there within the code's life, which is what a business listing postcard checks. It doesn't show who they are or that they own the place, so pair it with your own checks of the business and the person.
No. Holding the mail is the proof. They scan the code or type it at mailbox.bot/v or in your app, and nothing else is asked of them.
30 days by default, counted from the mail date; set qr.expires_days from 1 to 90. After that the code no longer verifies, and you can send a new piece with a new code.
Not in practice. A short code is 8 characters from 31 letters and digits, about 853 billion possibilities, and typing is limited to 10 tries per network in 10 minutes at mailbox.bot/v and 120 checks a minute per account on the API. Your key only ever sees your own pieces.
A postcard is cheaper ($1.05) and starts at one piece, but anyone who handles it can see the code. A letter ($1.15, from 10 pieces) carries the code inside the envelope.
Yes. Your app sends the code to POST /v1/batch-mail/verify with your key. The answer says verified, already_verified, the batch and piece, your ref and the time; a code that isn't yours returns 404 and an expired one 410.
batch.piece.confirmed when a piece is verified, with the batch and the piece: its number, your ref, the mode, the scan count and the times. batch.piece.scanned arrives on a piece's first scan. Both are signed and retried like every webhook, and go to your agent's callback too.
Nothing is sent and the code expires on its last day. The pieces list shows which pieces were verified, so you can send a new piece to the ones that weren't, or ask for another kind of proof.
Yes. With a sandbox key (sk_agent_test_) the batch runs for free and nothing is printed. Sandbox verify pieces show their short code so you can rehearse the verify call, and POST /v1/batch-mail/{id}/advance with qr_event plays a scan or a confirmation and sends the webhook.
No. Validation checks an address against USPS data and tells you it exists. Mail verification tells you someone there gets mail. Most teams validate when the address is typed and verify by mail before payouts, shipments or a listing go live.
The codes, the checks and the webhooks are included in the batch price: $1.05 for a 4×6 postcard, from one piece with a $2.00 fee under 10, or $1.15 for a one-sheet letter, printing and First-Class postage included. One postcard on its own is $3.05.
Send the addresses. We mail a one-time code to each, check every code that comes back, and show you who's verified.