Downgrade — release the N newest live mailboxes and lower the billed quantity.
Changed onReleases count MORE mailboxes than are currently released (RELATIVE, not a target fleet size) and syncs the lower Stripe quantity (proration_behavior 'none' — no mid-cycle credit; the lower price takes effect at the next renewal, minimum 3 mailboxes / $49; an account already paying keeps its own minimum). acknowledged: true is the quoted, irreversible-this-cycle consent this call requires.
A keyed call's FIRST attempt resolves and records WHICH mailboxes to release; every later call under the SAME Idempotency-Key can only ever finish that recorded set, whatever count it sends — a genuine second downgrade needs a NEW key. releasedCount can be less than the requested count: failedCount names how many the provider refused (still live, still billed) and unreleased lists those addresses — read them before concluding a downgrade landed. A 409 means a release is already running for this account.
Request
- Base URL: https://api.coldrig.dev
- URL: https://api.coldrig.dev/remove-mailboxes
- Auth: HTTP bearer
Headers
Optional, and strongly recommended on every mutating call. Resend the SAME key on retry: the first call runs, a replay with the same key returns the recorded result without re-executing — no duplicate campaign, no duplicate send, no second release of mailboxes. Honored on POST /campaigns, /setup-infrastructure, /remove-mailboxes and /threads/{id}/reply.
Only a FINISHED outcome replays. A call that returned while still owing work — a 202 that is still setup, or a /remove-mailboxes response whose failedCount is above zero because the provider refused a mailbox — is not recorded, so resending its key RE-RUNS the request and finishes the job instead of handing back the partial. That is what makes "retry with the same key" a true instruction rather than a guaranteed no-op; the response body always says which case you are in.
It is a REPLAY key, never a request discriminator: on /setup-infrastructure, changing it or omitting it does not cause anything extra to be set up. On /remove-mailboxes it is the only thing that makes a retry safe, because count is relative and releasing mailboxes cannot be undone through this API: the first call under a key records the exact mailboxes it resolved, so a same-key retry finishes that set and can never release one outside it, whatever count the retry carries.
The mechanism differs by transport — REST takes this as the Idempotency-Key header (this parameter); the MCP tools take the equivalent value as an idempotencyKey argument field instead, since MCP tool calls have no separate header channel.
Request body
Response
Release outcome (partial or complete — see failedCount/unreleased).
Changes
- warning
added the new
large_order_payment_pendingenum value to the///response property for the response status - info
added the optional property
/to the response with the status - info
added the optional property
/to the response with the status - info
added the optional property
////////to the response with the status - info
added the optional property
////////to the response with the status
- warning