---
title: "Create a test address | Proxy Mail QA"
description: "Developer docs for Proxy Mail QA: the MCP server for coding agents, the REST API for test suites, and the Chrome extension."
url: https://proxymail.qa/docs/reference/operations/createaddress
---

# Create a test address

POST

/v1/addresses

```js
const url = 'https://api.proxymail.qa/v1/addresses';
const options = {
  method: 'POST',
  headers: {
    'Proxy-Mail-QA-Test': 'sign-up%20%E2%80%BA%20sends%20one%20code',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"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"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
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](https://proxymail.qa/docs/reference.html#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 

```plaintext
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

```json
{
  "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

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

### 401

An error

Media typeapplication/json

### object

**error**

string

**message**

string

#### Example generated

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

### 402

An error

Media typeapplication/json

### object

**error**

string

**message**

string

#### Example generated

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

### 429

An error

Media typeapplication/json

### object

**error**

string

**message**

string

#### Example generated

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

[Previous List or find addresses in the project, newest first](https://proxymail.qa/docs/reference/operations/listaddresses.html) [Next One address, with its newest code or link](https://proxymail.qa/docs/reference/operations/getaddress.html)