{"openapi":"3.1.0","info":{"title":"DimeBox API","description":"Give an AI agent a real email identity - draft, send, and receive, priced in cents over the x402 protocol. No accounts, no API keys.","version":"1.0.0","contact":{"email":"hello@dimebox.app"}},"servers":[{"url":"https:\/\/dimebox.app"}],"externalDocs":{"description":"Full human-readable reference","url":"https:\/\/dimebox.app\/docs"},"paths":{"\/api\/emails\/generate":{"post":{"summary":"Draft an email from a brief","operationId":"generateEmail","x-x402-price":"$0.02","x-x402-network":"base","x-x402-asset":"USDC","x-x402-scheme":"exact","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"recipient":{"type":"string","format":"email","description":"Required."},"purpose":{"type":"string","maxLength":2000,"description":"Required."},"tone":{"type":"string","maxLength":100},"key_points":{"type":"array","items":{"type":"string","maxLength":500}},"sender":{"type":"string","maxLength":255}},"required":["recipient","purpose"]}}}},"responses":{"200":{"description":"Drafted email.","content":{"application\/json":{"schema":{"type":"object","properties":{"email":{"type":"object","properties":{"subject":{"type":"string"},"body":{"type":"string"}}},"paid_by":{"type":"string"}}}}}},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/inboxes":{"post":{"summary":"Provision an inbox with a random address (free)","operationId":"provisionRandomInbox","x-x402-price":"free","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"ai_drafting_enabled":{"type":"boolean","default":true},"webhook_url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"$ref":"#\/components\/responses\/InboxCreated"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"429":{"description":"Throttled - 5 requests\/hour per IP."}}}},"\/api\/inboxes\/claim":{"post":{"summary":"Provision an inbox with a chosen address","operationId":"claimInbox","x-x402-price":"$1.00","x-x402-network":"base","x-x402-asset":"USDC","x-x402-scheme":"exact","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":3,"maxLength":32,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"Required. Rejected if taken or reserved (system\/phishing-prone names)."},"name":{"type":"string","maxLength":255},"ai_drafting_enabled":{"type":"boolean","default":true},"webhook_url":{"type":"string","format":"uri"}},"required":["slug"]}}}},"responses":{"201":{"$ref":"#\/components\/responses\/InboxCreated"},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/inboxes\/{slug}\/send":{"post":{"summary":"Send from an inbox - drafted or raw","operationId":"sendFromInbox","x-x402-price":"$0.01","x-x402-network":"base","x-x402-asset":"USDC","x-x402-scheme":"exact","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email","description":"Required."},"subject":{"type":"string","maxLength":255,"description":"Required unless purpose is given, and the inbox has AI drafting enabled."},"body":{"type":"string","description":"Required unless purpose is given, and the inbox has AI drafting enabled."},"purpose":{"type":"string","maxLength":2000,"description":"Only valid if the inbox has AI drafting enabled - 422 otherwise."},"tone":{"type":"string","maxLength":100},"key_points":{"type":"array","items":{"type":"string","maxLength":500}}},"required":["to"]}}}},"responses":{"202":{"description":"Accepted, queued for background delivery.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/inboxes\/{slug}\/messages":{"post":{"summary":"Priority delivery to an inbox","operationId":"deliverPriorityMessage","x-x402-price":"$0.03","x-x402-network":"base","x-x402-asset":"USDC","x-x402-scheme":"exact","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"from":{"type":"string","maxLength":255},"subject":{"type":"string","maxLength":255},"body":{"type":"string"}},"required":["from","subject","body"]}}}},"responses":{"201":{"description":"Message delivered.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}},"get":{"summary":"Read an inbox's message history","operationId":"readInboxMessages","x-x402-price":"free","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Inbox-Token","in":"header","required":true,"schema":{"type":"string"},"description":"The read token shown once at provisioning time."}],"responses":{"200":{"description":"Paginated message history, newest first.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Missing or invalid X-Inbox-Token."}}}},"\/api\/inboxes\/{slug}\/messages\/{message_id}":{"get":{"summary":"Read one message's full details by its UUID","operationId":"readInboxMessage","x-x402-price":"free","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Inbox-Token","in":"header","required":true,"schema":{"type":"string"},"description":"The read token shown once at provisioning time."}],"responses":{"200":{"description":"The message. Scoped to this inbox - a message_id belonging to a different inbox 404s here.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"description":"Missing or invalid X-Inbox-Token."},"404":{"description":"No message with that message_id on this inbox."}}}},"\/api\/wallets":{"post":{"summary":"Start card-funded wallet creation (Stripe Checkout)","operationId":"createWallet","x-x402-price":"n\/a - card-funded, not x402","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Required."},"amount_cents":{"type":"integer","description":"Required unless pack is given."},"pack":{"type":"string","enum":["starter","growth","scale"],"description":"Required unless amount_cents is given."},"plan":{"type":"string","enum":["subscription"],"description":"Requires pack - a custom amount_cents can't recur."}},"required":["email"]}}}},"responses":{"200":{"description":"checkout_url to complete payment at.","content":{"application\/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string"},"notice":{"type":"string"}}}}}},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/wallets\/checkout\/{checkout_session_id}":{"get":{"summary":"Reveal a new wallet's id and secret exactly once, right after checkout","operationId":"revealWalletAfterCheckout","x-x402-price":"free","parameters":[{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#\/components\/responses\/WalletRevealed"},"404":{"description":"Nothing to reveal - either payment hasn't completed yet, or this was already shown once."}}}},"\/api\/wallets\/{id}":{"get":{"summary":"Balance and recent ledger for a wallet","operationId":"showWallet","x-x402-price":"free","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <wallet_secret>"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The wallet's public_id (wal_...)."}],"responses":{"200":{"description":"Wallet, balance, and up to 50 recent ledger entries.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"balance_cents":{"type":"integer"},"ledger":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#\/components\/responses\/InvalidWalletSecret"}}}},"\/api\/wallets\/{id}\/recharge":{"post":{"summary":"Top up a wallet - charges a saved card automatically if there is one","operationId":"rechargeWallet","x-x402-price":"n\/a - card-funded, not x402","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <wallet_secret>"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The wallet's public_id (wal_...)."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","description":"Required."},"force_checkout":{"type":"boolean","description":"Skip the saved-card attempt and go straight to a Checkout link."}},"required":["amount_cents"]}}}},"responses":{"200":{"description":"Charged the saved card - no checkout needed.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"balance_cents":{"type":"integer"}}}}}},"402":{"description":"No saved card (or it was declined) - checkout_url to complete payment at.","content":{"application\/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/InvalidWalletSecret"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/wallets\/{id}\/settings":{"patch":{"summary":"Set a persistent daily spend limit and\/or auto-reload preferences","operationId":"updateWalletSettings","x-x402-price":"free","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <wallet_secret>"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The wallet's public_id (wal_...)."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"spend_limit_cents":{"type":"integer","nullable":true,"description":"Rolling-daily cap across every route this wallet pays for. null clears it."},"auto_reload_enabled":{"type":"boolean"},"auto_reload_threshold_cents":{"type":"integer","nullable":true,"description":"Recharge once balance drops to\/below this. Required if auto_reload_enabled is true."},"auto_reload_amount_cents":{"type":"integer","nullable":true,"description":"How much to recharge by. Required if auto_reload_enabled is true."}}}}}},"responses":{"200":{"description":"Updated wallet.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"$ref":"#\/components\/responses\/InvalidWalletSecret"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/wallets\/{id}\/subscription":{"post":{"summary":"Attach a recurring monthly plan to a wallet that already exists","operationId":"attachWalletSubscription","x-x402-price":"n\/a - card-funded, not x402","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <wallet_secret>"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The wallet's public_id (wal_...)."}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"pack":{"type":"string","enum":["starter","growth","scale"],"description":"Required."}},"required":["pack"]}}}},"responses":{"200":{"description":"checkout_url to complete payment at - the subscription attaches to this wallet once Stripe confirms it.","content":{"application\/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string"}}}}}},"401":{"$ref":"#\/components\/responses\/InvalidWalletSecret"},"415":{"$ref":"#\/components\/responses\/UnsupportedContentType"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/wallets\/{id}\/subscription\/cancel":{"post":{"summary":"Cancel a wallet's subscription - its balance stays untouched and spendable","operationId":"cancelWalletSubscription","x-x402-price":"free","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <wallet_secret>"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The wallet's public_id (wal_...)."}],"responses":{"200":{"description":"Canceled.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"}}}}}},"401":{"$ref":"#\/components\/responses\/InvalidWalletSecret"},"422":{"description":"This wallet has no active subscription."}}}}},"components":{"responses":{"PaymentRequired":{"description":"Payment missing, invalid, or facilitator settlement failed. Not charged.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded payment requirements.","schema":{"type":"string"}}}},"UnsupportedContentType":{"description":"Body was not sent as Content-Type: application\/json. Rejected for free, before any payment challenge.","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"ValidationError":{"description":"Body failed validation. Not charged, even on a paid route.","content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object"}}}}}},"InboxCreated":{"description":"Inbox created. read_token (and webhook_secret, if set) are shown exactly once.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"read_token":{"type":"string"},"webhook_secret":{"type":"string","nullable":true},"paid_by":{"type":"string","nullable":true}}}}}},"WalletRevealed":{"description":"Wallet id and secret. The secret is never shown again after this call - there is no recovery.","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"wallet_secret":{"type":"string"},"notice":{"type":"string"}}}}}},"InvalidWalletSecret":{"description":"Missing or invalid Authorization: Bearer <wallet_secret>.","content":{"application\/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"securitySchemes":{"walletSecret":{"type":"http","scheme":"bearer","description":"A wallet secret from POST \/api\/wallets - closed-loop credit, an alternative to x402 for the same paid routes."}}}}