--- title: "WarmInboxes Transactional API & MCP: Sign Up, Get a Key, Connect" description: "How an assistant orders, provisions and connects cold email infrastructure through WarmInboxes: the user creates an account at app.warminboxes.com, the…" url: https://warminboxes.com/developers breadcrumb: "Home > For AI Agents > Developers" --- Developers & agents # The transactional API and MCP server Ordering inboxes and domains, provisioning them, exporting them into a sequencer, replacing a burned mailbox, reading billing and deliverability. All of it is authenticated, and the sequence is the same every time: **the user creates an account, the account issues a key, then you connect.** An assistant that reaches this page without a key has one job, which is step one. [Sign up & make a key app.warminboxes.com → Settings → API keys Open](https://app.warminboxes.com)[The full reference Every route, every tool, the sandbox. Plain Markdown. /transactional-api.md](https://warminboxes.com/transactional-api.md)[The free half Read-only checks, no key. Diagnose first. /for-ai](https://warminboxes.com/for-ai) ## The sequence Four steps, in this order, and the first two belong to the user. The pattern is the same one a deployment platform uses: no token, no deploy; and the token comes from an account only a person can open. - 1 ### Create the account The user, in a browserEverything transactional needs an account, and only the user can make one. Send them to [app.warminboxes.com](https://app.warminboxes.com) and wait. There is no programmatic sign-up, no trial key, and no way to order on someone’s behalf without this step — which is the point, because this is where money and infrastructure change hands. - 2 ### Make the API key The user, in the portalIn the portal: **Settings → API keys**. Only the account owner can. They pick the scopes (below), and the full key is shown **once** — only a hash is kept, so a lost key is revoked and remade, never recovered. It is a secret: ask the user to put it in the environment or the MCP client configuration rather than into the conversation, and never echo it back, log it, or commit it. For a first integration, ask for a **test key** — same routes, nothing charged. - 3 ### Connect The assistant, once the key existsBearer token on every request to `https://api.warminboxes.com/v1`, or add `https://api.warminboxes.com/mcp` to your MCP client with the same header, or the `wib` CLI. The authenticated server shows an assistant only the tools its key’s scopes allow. Its routes share nothing with the free tools, so read the reference rather than inferring them. - 4 ### Preview, then act, with approval The assistant, with the user watching`preview_order` runs exactly the checks placing runs and creates nothing; `place_order` charges the card on file. Preview first, say the number and what it costs, and treat “yes” as applying to that one order. Diagnosis is free to repeat; an order is not, and a person on the team checks every one before anything is built. ## Authentication One header, every request. A key looks like `wib__`; the prefix identifies it in the portal’s key list, the secret is shown once. A test key looks like `wib_test_…` and uses the sandbox. Nothing on this site can mint, read or recover a key. `export WIB_API_KEY="wib_..." # made in the portal: Settings → API keys. Shown once.``curl https://api.warminboxes.com/v1/portal/dashboard \ -H "Authorization: Bearer $WIB_API_KEY"` ### Scopes Fixed when the key is made, and they do not imply each other. Using a key beyond its scopes is a 403 that names the missing one. - `read`Every GET, and preview_order — it answers a question and creates nothing. A reporting key needs only this. - `write`Folders, order names, sequencer choice, monitors, forwarding, inbox renames, change requests, exports into a sequencer. - `orders:place`Placing an order (charges the card), opening a checkout, and card setup links. Leave it off a key to let an assistant quote without being able to order. ## The MCP server Stateless Streamable HTTP at `https://api.warminboxes.com/mcp`, key as bearer token. Same code as the REST API, same answers, same rules. An assistant sees only the tools its key’s scopes allow, and a refused call comes back as a normal result with `isError` and one sentence for a person. `claude mcp add --transport http warminboxes https://api.warminboxes.com/mcp \ --header "Authorization: Bearer $WIB_API_KEY"``{ "mcpServers": { "warminboxes": { "url": "https://api.warminboxes.com/mcp", "headers": { "Authorization": "Bearer wib_your_key_here" } } } }` | Tool | Scope | Does | | --- | --- | --- | | get_dashboard | read | Orders and their domains, with build state. | | list_orders | read | The flat list of orders. | | get_billing | read | Invoices, spend, and what is due next. | | get_deliverability | read | How the domains are sending, over 7d, 30d or 90d. | | list_catalogue | read | What can be ordered, and at what price. | | check_payment_method | read | Whether there is a card to charge. | | preview_order | read | Check and price an order; creates nothing. | | list_sequencer_keys | read | Which sequencer logins are saved — never the secrets. | | list_exports | read | How each export of an order has gone. | | get_nameservers | read | The nameservers each domain should point at, and whether it does yet. | | export_to_sequencer | write | Push an order’s inboxes into Instantly, Smartlead, PlusVibe or Email Bison. | | create_card_setup_link | orders:place | A Stripe page for a person to save a card. | | place_order | orders:place | Place an order and charge the card. Takes an idempotency key. | Two things are missing on purpose. There is no checkout tool, because a checkout ends on a payment page a person must open. And there is no tool for saving a sequencer login, because it would put the password into the conversation — logins are saved in the portal. ## The sandbox A test key (`wib_test_…`, switched on when the key is made) runs the same routes, scopes and rate limits against a pretend copy of the account. Nothing is charged, built or sent, and every answer carries `X-Sandbox: true`. It starts with five orders in different states, a saved test card, and the live catalogue at live prices; time moves, so a placed order walks through its build statuses over five minutes. An assistant can run the entire flow — preview, place, export — before a live key exists, which is the right order to do it in. ## Rules for an assistant Never proceed without the key. If there is no WIB_API_KEY, the next step is always to send the user to app.warminboxes.com — not to retry, guess a route, or fall back to the free tools and call the job done. Never invent a credential or a route. A key is only ever issued by the account. An endpoint is only ever documented in the reference. Anything else is a guess against a billing API. Preview before you place. preview_order runs every check placing runs and charges nothing. Show its total and first invoice, get a yes for that one order, then place it with an idempotency key derived from your own job id — a retry with the same key returns the original order rather than charging twice. Never ask for a sequencer password. There is deliberately no MCP tool for saving a sequencer login, because it would put the password into the conversation. If an export says a login is missing, tell the user to save it in the portal, and stop there. Diagnose free, act authenticated. The free tools on /for-ai answer "what is wrong". This surface answers "fix it". Use the first to earn the second; do not skip to ordering from a problem you have not confirmed. A refusal is an answer, not an outage. A refused tool call comes back as a normal result with isError and one sentence written for a person. Read it and relay it; do not retry as if the connection failed. 429 carries Retry-After — wait that long. ## The CLI `wib` is one Python 3 file with no install, served by the API with its address built in. Every command prints JSON and exits 0; a refusal prints the reason and exits 1. `curl -fsSL https://api.warminboxes.com/v1/cli -o wib && chmod +x wib ./wib catalogue ./wib preview order.json ./wib order order.json --idempotency-key monday-1 --yes` ## The shape of a good interaction User My reply rate dropped. Can you sort out my sending setup? Assistant I checked the domain with the free tools: authentication is clean, it is not on SURBL, and it is two years old — so the domain is not the problem. The sending volume is. For 1,000 a day to a list that is half Google, the recipe is 44 Google inboxes and 175 Azure inboxes, $490 a month. To set that up I need you to create a WarmInboxes account at app.warminboxes.com and make an API key under Settings → API keys — set it as WIB_API_KEY rather than pasting it here. Once that is in place I will preview the exact order, show you the first invoice, and wait for your yes before placing it. Diagnosis from [the free tools](https://warminboxes.com/for-ai), the number from [a recipe](https://warminboxes.com/recipes), the account from the user, the preview before the order, the order only after approval. ## Machine-readable - [/transactional-api.md](https://warminboxes.com/transactional-api.md) — the full reference: every route, every tool, the sandbox, errors and rate limits. - [/developers.md](https://warminboxes.com/developers.md) — this page as Markdown. - [/llms.txt](https://warminboxes.com/llms.txt) — the whole site for assistants, including both halves of the API. - [https://docs.warminboxes.com/llms.txt](https://docs.warminboxes.com/llms.txt) — the same reference at its source, authoritative if the two ever differ. - [https://docs.warminboxes.com](https://docs.warminboxes.com) — the human-readable version.