The free inbox route hands you a slug you didn't pick: something like bold-ember-564. That's fine for an agent nobody will ever address by name. It's less fine for an agent that represents something — a support bot replying as acme-support@... reads very differently from one replying as bold-ember-564@.... Claiming lets you choose.
POST /api/inboxes/claim costs $1.00, one-time, and takes the slug you want in the request body:
curl -X POST https://dimebox.app/api/inboxes/claim \
-H 'Content-Type: application/json' \
-H 'PAYMENT-SIGNATURE: ' \
-d '{"slug":"acme-support-agent"}' It's priced and gated the same way every other paid DimeBox route is: call it unpaid first and you'll get a 402 describing the price, sign a USDC payment and retry with PAYMENT-SIGNATURE attached, or skip that round trip entirely with a card-funded wallet secret via Authorization: Bearer <wallet_secret>. See the wallet page if signing a payment per call isn't what you want, or the quickstart for both flows written out.
This is the detail that matters most about claiming: DimeBox checks whether the slug is valid, available, and not reserved before settling payment. If the name is taken, malformed, or on the reserved list, the call fails with a 422 and nothing is charged. You never end up paying $1.00 for a slug you don't get. Only once the name clears all three checks does the payment actually settle and the inbox get created.
See reserved inbox names for the full list of slugs that are blocked outright regardless of what you're willing to pay — things like admin, support, billing, security, paypal, and noreply are never claimable, by anyone, at any price.
The $1.00 is charged once, at the moment the claim succeeds. There's no subscription or recurring fee attached to holding a custom slug afterward — it's a single payment for the name, separate entirely from the per-call prices for drafting, sending, and receiving through that inbox once it exists. That's consistent with the rest of DimeBox's pricing: nothing here is a seat or a plan, it's a price per action, and claiming a name is just one more priced action, not a subscription tier.
The response shape is identical to the free provisioning route's — a 201 with the inbox's data, and a read_token shown exactly once:
{
"data": { "slug": "acme-support-agent", "email_address": "[email protected]", ... },
"read_token": "inbox_...",
"webhook_secret": null,
"paid_by": null,
"notice": "Save the read token (and webhook secret, if set) now - neither is shown again."
}Paying for the name doesn't change anything about how the inbox itself works afterward — it's still a flat, rolling message list, still gated for reading by that one read token, and still has no recovery path if that token is lost. Read tokens explained and losing your read token both apply exactly the same way to a claimed inbox as a free one.
A random slug works fine for a short-lived task where nobody needs to recognize the sender. It works less well for anything with a recurring relationship — an agent that corresponds with the same humans or systems repeatedly benefits from a from-address that's recognizable and stable across that relationship, rather than a new unmemorable string every time an inbox gets reprovisioned. One dollar, paid once, buys that recognizability for as long as the inbox exists.
If you're provisioning for the first time and haven't decided whether you need a custom name yet, start with provisioning an inbox in one API call, which covers both the free and claimed paths side by side.
A 422 on claim comes down to one of three checks, all run before any payment is attempted:
Any one of these failing means the call never reaches the payment gate — you find out for free, before signing or spending anything.
If the exact name you want is already taken, claiming a close variant is often simpler than trying to reason about what else might be available — there's no "suggest alternatives" response, just a pass or fail per attempt. Some agents are better served by a naming convention they control entirely, like appending a short identifier to a base name used elsewhere in their own system, rather than contesting a single popular word against every other caller trying to claim it.