Check out an account from the pool

POST

/v1/addresses/checkout

curl --request POST \
  --url https://api.proxymail.qa/v1/addresses/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code' \
  --data '{ "tags": [ "example" ], "country": "example", "min_age": 1, "max_age": 1, "has_password": true, "search": "example", "site": "example", "environment": "example", "minutes": 10 }'

An account in the project that matches every filter given, that nobody else has checked out, and that lives past the hold: the least recently used first. It’s yours for minutes (default 10, at most 60): nobody else can check it out until you return it or the time runs out, which frees it on its own. Use the checkout.token to extend or return it. 409 when every matching account is checked out (saying when the first comes free), 404 when none match. Tag accounts with their state (verified, premium…) to make pools.

Authorizations

• apiKey

Parameters

Header Parameters

Proxy-Mail-QA-Run

string format: uuid

A run’s id (POST /v1/runs): adds what this call saw to the run. If it can’t be added (the run finished, or isn’t in this project), the call still works and the Proxy-Mail-QA-Run-Warning response header says why.

Proxy-Mail-QA-Test

string

<= 600 characters

With Proxy-Mail-QA-Run: the test this call belongs to, percent-encoded (encodeURIComponent), up to 200 characters once decoded. The run’s report shows it beside what the call saw.

Example

sign-up%20%E2%80%BA%20sends%20one%20code

Request Body

Media typeapplication/json

object

tags

Every one of these tags.

Array<string>

country

ISO 3166-1 alpha-2, such as DE.

string

min_age

integer

max_age

integer

has_password

boolean

search

Part of the address, label, notes, name or username.

string

site

Used on this site: a host or page URL.

string

environment

Used in this environment, such as staging.

string

minutes

integer

default: 10 >= 1 <= 60

Responses

200

The account, held for you

Media typeapplication/json

object

address

string

label

string | null

created_at

string format: date-time

expires_at

string format: date-time

persona

object

first_name

string | null

last_name

string | null

username

string | null

date_of_birth

Present only when the address has one.

string format: date

country

ISO 3166-1 alpha-2 code, such as GB. Present only when the address has one.

string

notes

string | null

tags

Array<string>

has_password

boolean

password

Only in the response to creating it with password: true.

string

site

Where it is used: the host of the app under test. Present only when set.

string

environment

Which environment it is used in, such as staging. Present only when set.

string

email_count

integer

latest

The newest code or link, like Match.

object | null

checked_out_until

Only while someone has it checked out of the pool.

string format: date-time

checkout

object

token

string format: uuid

until

string format: date-time

Example ^generated

{
  "address": "example",
  "label": "example",
  "created_at": "2026-04-15T12:00:00Z",
  "expires_at": "2026-04-15T12:00:00Z",
  "persona": {
    "first_name": "example",
    "last_name": "example",
    "username": "example",
    "date_of_birth": "2026-04-15",
    "country": "example"
  },
  "notes": "example",
  "tags": [
    "example"
  ],
  "has_password": true,
  "password": "example",
  "site": "example",
  "environment": "example",
  "email_count": 1,
  "latest": "example",
  "checked_out_until": "2026-04-15T12:00:00Z",
  "checkout": {
    "token": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "until": "2026-04-15T12:00:00Z"
  }
}

400

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}

404

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}

409

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

{
  "error": "example",
  "message": "example"
}