Most email providers put a form between you and a working address: sign up, verify, configure, maybe wait on approval. DimeBox skips all of it. One POST request returns a working email address and the credential to read it, and the request can come from a script with no prior relationship to DimeBox at all.
curl -X POST https://dimebox.app/api/inboxes \
-H 'Content-Type: application/json'That's the entire free path. No body is required. The response is a 201 with the new inbox's slug, its address, and — shown exactly once — a read_token:
{
"data": { "slug": "bold-ember-564", "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."
}There are two ways to provision an inbox, and they return the same response shape with one difference in how the slug is chosen:
POST /api/inboxes — free, no payment required, IP-throttled to three per day. The slug is generated for you in an adjective-noun-number format, something like steady-atlas-925.POST /api/inboxes/claim — $1.00 one-time, paid. You supply the slug you want in the request body, and it's yours if it's available and not reserved.Availability on the paid route is checked before payment settles — a taken or reserved name comes back as a 422 with no payment attempted, so you never pay for a slug you can't have. See claiming a custom inbox name for the full mechanics, and reserved inbox names for which slugs are permanently blocked regardless of what you offer to pay.
Because claim is a priced call, it goes through the same payment gate as every other paid DimeBox route: call it with a signed payment header, or skip the signing step entirely with a card-funded wallet secret.
# x402 — sign a payment and attach it
curl -X POST https://dimebox.app/api/inboxes/claim \
-H 'Content-Type: application/json' \
-H 'PAYMENT-SIGNATURE: ' \
-d '{"slug":"acme-support-agent"}'
# Wallet — skip the 402 round trip
curl -X POST https://dimebox.app/api/inboxes/claim \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{"slug":"acme-support-agent"}' Fund a wallet through the wallet page if you'd rather pay by card than sign a payment on every call, or see the quickstart for both the x402 and wallet flows end to end.
Both provisioning routes accept the same two optional fields in the request body, independent of whether you're using the free or claimed path:
ai_drafting_enabled (boolean) — set to false to provision a send-only inbox that rejects AI-drafted sends outright and only accepts raw, exact-wording mail. Useful if you never want an LLM call sitting between a brief and an outbound message.webhook_url — a URL DimeBox will POST a signed notification to whenever new mail arrives, instead of making you poll for it. See the webhook notifications guide for setup and signature verification.The read_token in the response is the only credential that can read this inbox's messages later, via the X-Inbox-Token header on GET /api/inboxes/{slug}/messages. It is shown exactly once, at creation. There's no recovery flow if you lose it, so the first thing your code should do after this call succeeds is persist that token somewhere durable, not just hold it in memory. Read tokens explained covers the model in depth, and losing your read token walks through what happens if you skip that step.
Once the inbox exists, the next calls are usually drafting and sending from it or setting up a channel to receive mail. Both are separate, separately priced calls from provisioning itself — creating the inbox is just step one.
The free route is limited to three inboxes per IP per day. A fourth attempt from the same IP within the same day returns a 429 rather than creating another inbox. This isn't a billing event — there's nothing to pay to lift it, and no partial inbox gets created in the background while you wait it out. If an agent genuinely needs more than three free inboxes in a day from one IP, the paid claim route doesn't carry the same per-IP cap, since price rather than a rate limit is what keeps that route from being abused.
The two routes aren't really a "free tier" and a "premium tier" — they solve different problems. The free route is right when the address itself is disposable: a one-off task, a throwaway address to receive a single confirmation, anything where nobody needs to recognize or remember the sender. The claim route is worth the dollar when the slug itself carries meaning — an address a human will see repeatedly, or one that needs to look deliberate rather than randomly generated. Both produce an inbox with identical capabilities afterward; the only difference is how the slug was chosen and whether a one-time fee was involved in choosing it.