Create a test address

POST

/v1/addresses

curl --request POST \
  --url https://api.proxymail.qa/v1/addresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code' \
  --data '{ "label": "example", "name": "example", "persona": false, "password": false, "lifetime_days": 1, "domain": "example", "age": "adult", "date_of_birth": "2026-04-15", "country": "example", "site": "example", "environment": "example" }'

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

label

What it is for, e.g. “Checkout test”.

string

name

A custom name before the @: 3–64 lowercase letters, digits, dots (not first, last or doubled) or any of ! # $ % & ’ * - / = ? ^ _ ` { | } ~. Random when left out.

string

persona

Also generate a fictional first name, last name and username.

boolean

password

Also generate a strong password for the sign-up form and save it on the address. It is returned once, in this response; reading it again needs a key with “Can read saved passwords”.

boolean

lifetime_days

Defaults to the plan’s maximum.

integer

>= 1

domain

One of the project’s mail domains (GET /v1/project). Defaults to the project’s.

string

age

Give the persona a date of birth for this age: adult (18 to 65), over21, under18 (15 to 17), under15 (13 or 14), under13 (8 to 12), any (8 to 80), or someone who turns 18 tomorrow or turned 18 today. Leave out for no date of birth.

string

Allowed values: adult over21 under18 under15 under13 any turns18tomorrow turned18today

date_of_birth

A date of birth to use instead of age, YYYY-MM-DD.

string format: date

country

Where the persona lives, as an ISO 3166-1 alpha-2 code such as GB or US (persona.country). Leave out for none.

string

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

site

Where the account is used: the host or a page URL of the app under test, kept as the host.

string

<= 300 characters

environment

Which environment of the app, such as staging, qa or local.

string

<= 40 characters

Responses

201

The new address. With password: true, it also has password, shown this once.

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

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

400

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

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

401

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

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

402

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

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

429

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

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