Skip to main content
The pool holds paid Google domains with warmed inboxes, commonly two per domain. Add domains once, preview an exact quantity, attach them to a workspace, and release them when the assignment ends. This flow is separate from normal ordering. POST /orders never reads, reserves, attaches, or changes pool inventory. Only POST /pool/attach assigns pre-warmed domains.

​
1. Create the routing target

Call POST /workspaces first and keep the returned workspace_id. Workspace creation does not use an Idempotency-Key. For Smartlead, connect the main workspace. Do not send client_id or customer data. The login pair is optional, but it must be complete when sent:
Peeker never returns the login values. If the pair is missing when an upload needs it, attach returns 422 provider_login_credentials_required before reserving any pool domain. Connect the same workspace again with the pair, then retry the attach.

​
2. Add paid domains

POST /pool/add adds domains from a paid Google order that already has active inboxes.
Each domain must have active billing and at least one active Google inbox (commonly two). Every inbox must also have the provider mailbox IDs needed for a later username swap. The whole request passes or nothing changes. This call does not create an order or change billing. A domain becomes available only after all of these are true:
  • Its original subscription start plus warming_days has passed (default 14; whole numbers from 1 to 365). Adding later does not restart this clock.
  • Any post-release hold has ended.
  • Its inboxes are active.
Provider health stays visible on the pool row but does not block an otherwise ready domain, including an explicit burned result. The subscription schedule, active billing, mailbox identity, and forwarding checks still apply. Peeker administrators can set an exact availability deadline for enrolled inventory. That replaces the subscription-based deadline for the current warming cycle; billing, provisioning and release holds still apply. The admin partner page and ListKit reports display the same schedule. With a sandbox key, initial and post-release warmups are five seconds instead of 14 days. POST /pool/add may therefore return a new domain with status warming. Poll GET /pool?availability=available until it appears before previewing or attaching it.

​
Remove unassigned domains

POST /pool/remove removes available, warming, or idle quarantined domains from active pool inventory. It leaves the paid order, inboxes, subscriptions, and billing unchanged.
Send 1 to 25 exact domain names. If any domain is assigned, reserved, releasing, or linked to active pool work, the API returns 409 and removes nothing. A domain that was already removed or never pooled returns absent, so retries are safe. Add a removed domain again with POST /pool/add when its paid Google inboxes are still eligible.

​
3. Preview an exact quantity

You get all 20 domain names or insufficient_inventory. A preview does not reserve them. Peeker tries not to show the same domains in two concurrent previews for five minutes, but can reuse an unclaimed preview when inventory is tight. Use GET /pool?availability=available when you need to list ready inventory. Follow the next link until it is null.

​
4. Attach the domains

Send the previewed domain names and the public workspace target:
Generate a new idempotency key for each attach. Reuse that key only when retrying the same attach request. Existing callers that omit the header remain supported: an exact retry reuses the live reservation instead of reserving again. An unfinished release still blocks a duplicate. A failed attach or completed release permits a fresh reservation, so the header is still the safest option. Omit client_id to attach to the Smartlead main workspace. Include it for one client workspace:
Peeker keeps the submitted main workspace_id in the reservation and resolves the client behind it. No email, user, or customer object is needed. You can send 1 to 10 personas. Prefer usernames for exact mailbox local parts: one persona may list multiple aliases (for example alex and alex.r). For usernames, Peeker keeps the first local parts that fit each domain’s inbox count, generates any missing seats from the persona names, and ignores extras. Legacy email (a full address, one per persona) still works when every persona includes it; those domains must have at least that many inboxes. Otherwise omit both fields and Peeker creates the usernames from the names. If a submitted domain is no longer ready, Peeker uses the oldest ready domain instead. If it cannot fill the whole request, nothing is assigned. Before reserving anything, Peeker checks that every selected domain has complete provider mailbox identity. It also checks that Smartlead and PlusVibe targets have a complete saved login pair. Missing target login returns 422 with provider_login_credentials_required and reserves nothing. When forwarding_url is present, Peeker checks that every selected domain has an active Cloudflare zone and account. A domain failure returns 422 with code domains_not_submittable and one reason per blocked domain:
  • google_engine_identity_incomplete
  • forwarding_not_ready
No inventory is reserved when this check fails. Fix the reported setup issue, then retry the same request and idempotency key. 202 means the assignment was accepted. Peeker then updates forwarding, submits one Google username swap per domain, and uploads the inboxes to the destination workspace. The response maps each requested_domain to the final domain and says if it was substituted. Poll the returned reservation_id:
You can also listen for pool.claim.completed and pool.claim.failed. reserved and renaming remain in progress while Peeker retries provider or network attempts. action_required is used only when fulfillment needs a customer or partner change. failed means fulfillment was explicitly stopped; Peeker does not fail an accepted reservation because a retry limit was reached.

​
Sandbox behavior

Sandbox uses the same requests, response shapes, polling, and webhooks as live. Workspace credentials are checked for the right shape and stored, but sandbox uses a local provider identity instead of validating them with the sequencer. Use placeholder credentials, never production provider keys. Sandbox orders create local Cloudflare test records, but they do not create or change pool rows. Pool rows enter through POST /pool/add and can leave through POST /pool/remove or the assignment lifecycle. Sandbox attach records forwarding changes and simulates username swaps without calling Cloudflare, the mailbox provider, or the destination sequencer. Before switching to a live key:
  1. Confirm GET /me reports api_key.environment: "live".
  2. Confirm the destination workspace credentials are valid.
  3. Confirm each pool domain has complete provider mailbox identity and an active Cloudflare connection when forwarding is requested. Review its health signal separately; a burned signal does not block attach.
  4. Ask Peeker to configure the live pool recycle forwarding URL before releasing any reservation that used forwarding.
  5. Use a unique idempotency key for each new attach.
  6. Treat 202 as accepted work and poll until the reservation is terminal.

​
5. Return the domains when the customer cancels

When a customer cancels, release their reservation. By default the domains come back on the next monthly date from the original attach, so the customer keeps sending until the end of their current month:
The response includes effective_at. Add "forced": true to take the domains back immediately. If a release is already scheduled, sending the forced request moves that same release to now. It does not create a second release. Poll GET /pool/releases/{id} or listen for pool.release.completed and pool.release.failed. Peeker retries temporary forwarding or Google Engine errors up to three total attempts, one minute apart. The release stays scheduled during those retries. Permanent setup errors fail immediately, and a temporary error emits pool.release.failed only after the final attempt. Release uses the same cleanup as Admin: detach the reservation’s inboxes from its Smartlead client, remove its forwarding, and clear its Google Engine client links. Once every cleanup is verified, all domains return directly to available. Inbox addresses stay unchanged. Release does not rename, re-upload, re-warm, quarantine, or replace domains; sender identities change on the next claim. A recycle forwarding URL is not required. Source-order billing is unchanged. This cleanup requires a Smartlead reservation assigned to a customer client. Direct workspace destinations and other providers return an error before reserving a release. Sandbox simulates provider cleanup, except explicitly enabled live Smartlead execution still detaches real accounts. Releases admitted before this change keep their existing workflow. In-flight rename jobs must be reconciled before an old release can move to detach cleanup.

​
What happens when a domain is burned

Peeker runs two separate replacements:
  1. The customer gets an available warmed domain. Pool health stays visible but does not block that candidate. Based on your pool setting, this starts at once, waits for your approval, or stays off. It has its own reservation and pool.replacement.* webhooks.
  2. The pool gets a bought backup domain. Peeker cancels the old inboxes, clears the old stats, and creates new inboxes under the same original order and billing. Billing is not changed.
The backup gets new sender names, the pool forwarding URL, matching inbox count for that domain, and a full warmup period. It cannot be shown as available until provisioning finishes. If no bought backup is ready yet, the pool waits until one is available, then continues automatically.
Last modified on September 12, 2026