Change its label, notes, tags or persona

PATCH

/v1/addresses/{address}

curl --request PATCH \
  --url https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "label": "example", "notes": "example", "tags": [ "example" ], "first_name": "example", "last_name": "example", "username": "example", "date_of_birth": "2026-04-15", "country": "example" }'

Send only the fields to change; null or an empty string clears one. Use it when the app under test changed the first name, last name or username, so the saved persona still matches. To change the password, use PUT /v1/addresses/{address}/password.

Authorizations

• apiKey

Parameters

Path Parameters

address

required

string format: email

The test address, URL-encoded. A variant also works: capitals, or a +tag (k7f2x9ab12cd+o’brien@mailclub.dev). It acts on the plain address; waiting on a +tag variant, or listing its messages, only finds mail sent to that variant.

Example

k7f2x9ab12cd@mailclub.dev

Request Body

Media typeapplication/json

object

label

string | null

notes

string | null

<= 2000 characters

tags

Array<string>

first_name

string | null

<= 60 characters

last_name

string | null

<= 60 characters

username

string | null

<= 40 characters

date_of_birth

YYYY-MM-DD; null clears it.

string | null format: date

country

ISO 3166-1 alpha-2 code such as GB; null clears it.

string | null

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

Example ^generated

{
  "label": "example",
  "notes": "example",
  "tags": [
    "example"
  ],
  "first_name": "example",
  "last_name": "example",
  "username": "example",
  "date_of_birth": "2026-04-15",
  "country": "example"
}

Responses

200

The address

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

404

An error

Media typeapplication/json

object

error

string

message

string

Example ^generated

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