Skip to content
Docs

List or find addresses in the project, newest first

GET
/v1/addresses
curl --request GET \
  --url 'https://api.proxymail.qa/v1/addresses?limit=50' \
  --header 'Authorization: Bearer <token>'

Every filter given must match, so an agent or test can find a test account it made earlier, such as an under-18 in GB with a saved password: ?tag=age-gate&country=GB&max_age=17&has_password=true.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 200
before
string format: date-time

Addresses created before this time (paging).

tag
Array<string>
<= 20 items

Addresses with this tag. Repeat it, or separate tags with commas, to need all of them.

country
string
/^[A-Za-z]{2}$/

The persona’s country, an ISO 3166-1 alpha-2 code such as GB.

min_age
integer
<= 120

At least this age today, in whole years, from the persona’s date of birth.

max_age
integer
<= 120

At most this age today: max_age=17 finds under-18s.

has_password
boolean

Whether a password is saved on the address.

search
string
<= 200 characters

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

site
string
<= 300 characters

Used on this site: a host or page URL, such as staging.example.com.

environment
string
<= 40 characters

Used in this environment, such as staging.

Responses

Section titled “Responses”

200

Section titled “200”

Addresses

Media typeapplication/json
Array<object>
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

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"
  }
]

401

Section titled “401”

An error

Media typeapplication/json
object
error
string
message
string

Example generated

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