Authentication All public API requests require an API key in the X-API-Key header. Bearer token authentication is only used by the signed-in web app, not by the public API.
curl https://app.simpleinboxes.com/api/v1/orders \
-H "X-API-Key: si_live_your_api_key"Create and manage API keys from your dashboard API Keys page after signing in. Key creation and revocation require a dashboard session, so those endpoints are not listed as public API-key-auth endpoints here.
Base URL https://app.simpleinboxes.com/api/v1Endpoint paths below are relative to this base URL. Requests and responses use JSON.
Errors All errors return a consistent JSON shape with a machine-readable code and a human-readable message.
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Order not found"
}
}400 INVALID_REQUESTMissing or invalid parameters
401 MISSING_API_KEY / INVALID_API_KEYInvalid or missing API key
404 NOT_FOUNDResource not found
429 RATE_LIMIT_EXCEEDEDToo many requests
500 SERVER_ERRORInternal server error
Orders Create, list, update, cancel, and reactivate inbox orders. Includes inbox-mutation jobs (renames, password rotations, profile-photo updates) and bulk nameserver checks.
GET /ordersList all orders. Filter by client, workspace, or status. ... POST /ordersPlace a new inbox order. Pricing, domain purchase costs, ... GET /orders/:orderIdGet a single order by ID, including its inboxes, domain, ... GET /orders/promo-statusCheck active promo eligibility for the authenticated work... GET /orders/stats/inbox-countGet aggregate inbox counts (active, pending, canceled) fo... GET /orders/unpaidList orders that still have an outstanding balance. PATCH /orders/:orderId/auto-renewToggle auto-renew on a per-order basis. POST /orders/:orderId/cancelQueue an order for cancellation. Inboxes stay active unti... POST /orders/:orderId/revert-cancellationRevert a queued cancellation before it processes. POST /orders/:orderId/reactivateReactivate a previously canceled order. POST /orders/inbox-mutationsQueue an inbox-mutation job — username rename, password r... GET /orders/inbox-mutationsList queued/processed inbox-mutation jobs. GET /orders/inbox-mutations/:idGet the status of a specific inbox-mutation job. POST /orders/nameservers/checkRe-check nameserver propagation for a single domain. POST /orders/nameservers/recheck-allTrigger a fleet-wide nameserver recheck for the workspace. Inboxes List inboxes, retrieve credentials, manage MFA, and rotate passwords or profile photos at the inbox level.
GET /inboxesList inboxes across the workspace. Filter by domain, stat... GET /inboxes/:inboxIdGet a single inbox by ID, including its domain, persona, ... GET /inboxes/:inboxId/credentialsRetrieve the inbox's app password / SMTP credentials. GET /inboxes/:inboxId/mfaFetch the current MFA setup state for the inbox. POST /inboxes/:inboxId/sync-1passwordPush the inbox's credentials into your linked 1Password v... PATCH /inboxes/:inboxId/profile-photoUpdate the inbox profile photo (multipart upload). PATCH /inboxes/:inboxId/passwordRotate the inbox password. Domains Search the registrar marketplace, manage owned domains, retrieve nameservers, run bulk DNS jobs, and reupload to sending tools.
GET /domainsList all domains in the workspace. Filter by client or st... GET /domains/searchSearch the Dynadot registrar marketplace for available do... POST /domains/search-batchBulk-search up to 100 domains in a single call. POST /domains/bulk/dnsRun a bulk DNS update across many domains in one call. GET /domains/:domainGet detailed info for a single domain. GET /domains/:domain/inboxesList all inboxes on a domain. GET /domains/:domain/nameserversGet the assigned Cloudflare nameservers + propagation sta... GET /domains/:domain/historyGet the full lifecycle history for the domain (provisioni... GET /domains/:domain/actionsList queued/in-progress actions on this domain. POST /domains/:domain/actions/:actionId/retryRetry a failed provisioning action on the domain. POST /domains/:domain/reuploadRe-push the domain's inbox credentials to your linked sen... POST /domains/:domain/add-sending-toolAttach a sending-tool credential to the domain so future ... PATCH /domains/:domain/fulfillment-settingsOverride per-domain fulfillment defaults (forwarding URL,... DNS Records Manage SPF / DKIM / DMARC / MX / custom records on every domain. All edits are auto-synced to Cloudflare.
GET /domains/:domain/dnsGet all DNS records for a domain. POST /domains/:domain/dnsAdd a DNS record. DELETE /domains/:domain/dns/:recordIdDelete a DNS record by ID. POST /domains/:domain/dns/syncForce a full DNS sync to Cloudflare. POST /domains/:domain/dns/sync-recordSync a single DNS record by ID. POST /domains/:domain/dns/forwardingConfigure URL forwarding for the domain. Workspaces Per-client workspaces for agency mode. Create, list, update, and configure sending-tool defaults at the workspace level.
GET /workspacesList all workspaces in your agency account. POST /workspacesCreate a new workspace. GET /workspaces/global/summaryAggregate spend, inbox count, and order count across ever... PATCH /workspaces/:idUpdate workspace name, billing mode, or fallback settings. GET /workspaces/:id/summaryPer-workspace spend, inbox count, and recent activity. GET /workspaces/:id/sending-tool-defaultsGet the default sending-tool credentials new orders inherit. PUT /workspaces/:id/sending-tool-defaultsUpdate the default sending-tool credentials for the works... Clients Legacy clients API — name-keyed wrapper around workspaces. Manage clients, sending-tool credentials, and saved usernames.
GET /clientsList all clients with order and inbox counts. POST /clientsCreate a new client. GET /clients/:clientNameGet detailed info for a client. PUT /clients/:clientNameRename a client. DELETE /clients/:clientNameDelete a client workspace. GET /clients/:clientName/usernamesGet all unique usernames for a client. GET /clients/:clientName/credentialsGet saved sending-tool credentials for a client. Filter b... POST /clients/:clientName/credentialsAdd a sending-tool credential for a client. POST /clients/:clientName/credentials/testValidate a credential against the sending tool's API befo... PUT /clients/:clientName/credentials/:credentialIdUpdate a credential. DELETE /clients/:clientName/credentials/:credentialIdDelete a credential. Recovery Pool Park burned, dormant, or unused domains so we restore their sender reputation. Submit blacklist removal requests, track health lights, and reactivate domains once they're ready.
GET /recoveryList every domain in your Recovery Pool with current heal... POST /recovery/domainsSubmit one or more domains directly into the Recovery Poo... POST /recovery/blacklist-checkRun a fresh blacklist check against Spamhaus DBL, URIBL, ... GET /recovery/pending-notificationsList unread Recovery Pool notifications (ready-to-reactiv... GET /recovery/:idGet a single Recovery Pool entry by ID. POST /recovery/:id/reactivatePull a healed domain back into your account and re-provis... POST /recovery/:id/dismiss-bannerAcknowledge an in-app banner for the domain. DELETE /recovery/:idPermanently remove a domain from the Recovery Pool. Registrars Auto-update nameservers at supported registrars (Porkbun, Spaceship, Name.com, Namecheap) via saved API credentials. No more clicking through registrar dashboards.
GET /registrars/supportedList supported registrar integrations and their credentia... GET /registrars/connection-infoGet the SimpleInboxes outbound IP needed to allowlist (Na... POST /registrars/test-credentialsValidate registrar API credentials before saving. POST /registrars/update-nameserversUpdate nameservers for one or more domains using saved re... Wallet Master + per-workspace wallets, transaction ledger, transfers, auto-recharge, and billing-mode toggles.
GET /walletGet current wallet balance and auto-recharge settings. GET /wallet/transactionsList wallet transactions. Filter by type ("credit" / "deb... GET /wallet/overviewAggregated wallet view across master + every workspace. POST /wallet/auto-rechargeConfigure automatic top-ups when balance falls below a th... POST /wallet/workspaces/:workspaceId/modeSwitch a workspace between master-billing and dedicated-w... POST /wallet/workspaces/:workspaceId/fallbackConfigure fallback to master billing if a dedicated works... POST /wallet/workspaces/:workspaceId/use-master-billingForce a workspace to use the master wallet for all charges. POST /wallet/workspaces/:workspaceId/billing-detailsSave per-workspace billing details (company, address, VAT). POST /wallet/transferMove funds between master and workspace wallets. Billing Invoices, billing history, custom invoices, and per-workspace billing details.
GET /billing/summaryCurrent month-to-date spend, projected total, and breakdo... GET /billing/historyPast billing periods (monthly statements). GET /billing/invoicesList all Stripe invoices (subscriptions + one-off). GET /billing/topup-invoicesWallet top-up invoices specifically. GET /billing/custom-invoicesCustom (manually created) invoices. GET /billing/custom-invoices/:transactionIdSingle custom invoice by transaction ID. GET /billing/detailsWorkspace billing details (company name, address, VAT). POST /billing/detailsUpdate billing details for the workspace. Payments Stripe-backed top-ups, payment methods, and the Customer Portal.
POST /payments/topupCreate a Stripe top-up session. Returns a checkout URL fo... POST /payments/confirmConfirm a top-up after the customer returns from Stripe. GET /payments/methodGet the saved default payment method on file. POST /payments/setup-intentCreate a Stripe SetupIntent for adding a new card. POST /payments/customer-portalGenerate a one-time URL into the Stripe Customer Portal. API Keys Programmatically manage your own API keys. (Key creation & revocation are also available in the dashboard.)
GET /api-keysList all API keys for the workspace, with last-used and c... POST /api-keysCreate a new API key. The full key is returned ONCE — sto... DELETE /api-keys/:keyIdRevoke an API key. Effective immediately.