remove_mailboxes
Release your newest live mailboxes now to lower your billed quantity. This action requires acknowledged, irreversible consent; the lower monthly rate applies at the next renewal.
Instructions
Downgrade: release your N NEWEST live mailboxes now and lower the billed quantity. Inputs: count, acknowledged (must be true — this is a quoted, irreversible-this-cycle consent: the release is immediate for provisioning but there is NO mid-cycle credit; the lower price takes effect next renewal, minimum 5 mailboxes / $99). Returns { releasedCount, failedCount, unreleased, billing, deduplicated } where billing is the new projected monthly. releasedCount is what COMPLETED and can be less than the count you asked for; failedCount is how many the provider refused, which are STILL LIVE and still billed, and unreleased names those addresses — read them before concluding a downgrade landed. deduplicated: true means this call did NOT re-perform the downgrade — every count above describes an EARLIER call's already-recorded outcome under the same idempotencyKey, not new work done just now. This can be true even after the 30-day idempotency window itself has expired: the underlying release record persists independently, so a reused key still reports no re-release rather than silently starting a fresh one. count is RELATIVE — it releases that many MORE mailboxes, it does not set your fleet to that size — and release cannot be undone through this API, so ALWAYS pass an idempotencyKey: the FIRST call under a key resolves WHICH mailboxes to release and records that exact set, so every later call carrying the SAME key can only ever finish that same set. A same-key retry re-attempts the stragglers and can never release a mailbox outside them, whatever count you send with it (the recorded set wins over a changed count); a retry WITHOUT a key always releases another count. A genuine SECOND downgrade is therefore a NEW key — reusing an old one can only ever finish what that key already asked for. A call that came back with failedCount above zero did NOT finish, so its key is not frozen: resend the identical request with the same key until failedCount is 0 — from then on that key replays the finished result and releases nothing further. If a call returns 409 a release is already running for this account: wait, then re-read infrastructure_status before deciding whether to retry. To ADD mailboxes use setup_infrastructure / configure_byo_domain (request_managed_mailboxes).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | ||
| acknowledged | Yes | ||
| idempotencyKey | No | Optional idempotency key: resend the SAME key when retrying this call so a dropped-response retry is not applied twice (no duplicate campaign/provision/send). |