Attach pool domains

Attach an exact set of pre-warmed domains to a connected workspace. This is the only order flow that reserves or changes pool inventory. Normal POST /orders requests never use the pool.

Ready names stay assigned even when their health signal says burned. Missing or claimed names are replaced with the oldest ready options. If Peeker cannot fill the full request, nothing changes. 202 means the domains are reserved and processing. Poll the reservation or subscribe to pool.claim.*.

Send the provider and public workspace_id. For Smartlead, omit client_id for the main workspace or include it for one client. No user or customer object is needed. Peeker checks the saved upload credentials before it reserves anything. A missing Smartlead or PlusVibe login pair returns 422 provider_login_credentials_required and leaves the pool unchanged.

Peeker also checks every selected domain before reservation. Missing Provider mailbox identity, or missing Cloudflare readiness when forwarding_url is sent, returns 422 with code domains_not_submittable. error.details.failures identifies each blocked domain with google_engine_identity_incomplete or forwarding_not_ready. No inventory is reserved.

Sandbox records forwarding locally and simulates username swaps. It does not call Cloudflare, the mailbox provider, or the destination sequencer.

POST

pool

attach

curl --request POST \
  --url https://api.peeker.ai/partner/v1/pool/attach \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domains": [
    "warm-one.example",
    "warm-two.example"
  ],
  "destination": {
    "provider": "plusvibe",
    "workspace_id": "wrk_01HZX0NP1A2B3C4D5E6F7G8H"
  },
  "personas": [
    {
      "first_name": "Alex",
      "last_name": "Rivera",
      "usernames": [
        "alex",
        "alex.r"
      ]
    }
  ]
}
'

{
  "data": {
    "reservation_id": "pcl_01HZX0PC1A2B3C4D5E6F7G8H",
    "status": "reserved",
    "step": "<string>",
    "domain_count": 250,
    "inbox_count": 501,
    "destination": {
      "provider": "emailbison",
      "workspace_id": "<string>",
      "client_id": "<string>"
    },
    "domains": [
      {
        "requested_domain": "warm-domain.example",
        "substituted": true,
        "domain": "acme-mail.com",
        "provider": "google",
        "inbox_count": 2,
        "assignable_inbox_count": 1,
        "assigned_inbox_count": 1,
        "held_inbox_count": 1,
        "availability": "available",
        "status": "warming",
        "health": {
          "verdict": "healthy",
          "reasons": [
            "<string>"
          ],
          "checked_at": "2023-11-07T05:31:56Z"
        },
        "available_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "released_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

Authorizations

Authorization

string

header

default:Bearer pk_test_<your-test-key>

required

Partner API key (pk_live_… or pk_test_…).

Headers

Idempotency-Key

string

Recommended for durable retries. Without this header, an exact replay reuses the same live reservation, including one whose release is unfinished. A failed attach or completed release permits a fresh reservation.

Required string length: 1 - 256

Body

application/json

domains

string[]

required

Domain names from preview. Peeker returns the final name for every entry.

Required array length: 1 - 500 elements

destination

object

required

Show child attributes

personas

object[]

required

Either every persona includes usernames (preferred mailbox local parts / aliases), every persona includes legacy email, or neither. Do not mix modes. Peeker fits the identities to each domain's inbox count, generates missing identities, and ignores extras that do not fit the selected domains.

Required array length: 1 - 10 elements

Show child attributes

forwarding_url

string<uri> | null

Response

Durable pool reservation and attach state.

data

object

required

Show child attributes

Last modified on August 25, 2026

curl --request POST \
  --url https://api.peeker.ai/partner/v1/pool/attach \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domains": [
    "warm-one.example",
    "warm-two.example"
  ],
  "destination": {
    "provider": "plusvibe",
    "workspace_id": "wrk_01HZX0NP1A2B3C4D5E6F7G8H"
  },
  "personas": [
    {
      "first_name": "Alex",
      "last_name": "Rivera",
      "usernames": [
        "alex",
        "alex.r"
      ]
    }
  ]
}
'

{
  "data": {
    "reservation_id": "pcl_01HZX0PC1A2B3C4D5E6F7G8H",
    "status": "reserved",
    "step": "<string>",
    "domain_count": 250,
    "inbox_count": 501,
    "destination": {
      "provider": "emailbison",
      "workspace_id": "<string>",
      "client_id": "<string>"
    },
    "domains": [
      {
        "requested_domain": "warm-domain.example",
        "substituted": true,
        "domain": "acme-mail.com",
        "provider": "google",
        "inbox_count": 2,
        "assignable_inbox_count": 1,
        "assigned_inbox_count": 1,
        "held_inbox_count": 1,
        "availability": "available",
        "status": "warming",
        "health": {
          "verdict": "healthy",
          "reasons": [
            "<string>"
          ],
          "checked_at": "2023-11-07T05:31:56Z"
        },
        "available_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true
    },
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "completed_at": "2023-11-07T05:31:56Z",
    "released_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

{
  "error": {
    "code": "emailbison_super_admin_key",
    "message": "Use an EmailBison workspace/user API key; super-admin keys are not accepted.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "field": "credentials.api_key",
    "details": {}
  }
}

Account

Provider workspaces

Bundles

Domains

Domain pool

Orders

Domain swaps

Attach pool domains

Authorizations

Headers

Body

Response