---
title: "Test addresses to clean up from your app | 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/cleanuplist
---

# Test addresses to clean up from your app

GET

/v1/cleanup-list

```js
const url = 'https://api.proxymail.qa/v1/cleanup-list';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

```sh
curl --request GET \
  --url https://api.proxymail.qa/v1/cleanup-list \
  --header 'Authorization: Bearer <token>'
```

Every test address the key’s project used between from and to (30 days ago to now by default; from can’t go back past 90 days): one made on or before to that was still live, or ended, on or after from. They come newest first, live, expired or deleted, so you can delete those test users from the app under test. A gone address stays on the list until 90 days after it ended, or until its project, account or organisation is deleted. Proxy Mail QA never touches your app. mail\_domains lists the domains every test address ends in, to filter your users by. Up to 5,000; truncated says there were more. See <https://proxymail.qa/docs/rest-api#test-users-to-delete>.

## Authorizations

- **[apiKey](https://proxymail.qa/docs/reference.html#apikey)**
- **[apiKeyHeader](https://proxymail.qa/docs/reference.html#apikeyheader)**

## Parameters

### Query Parameters

**from**

string format: date-time

<= 35 characters

Addresses still live, or ended, on or after then. Defaults to 30 days ago, and can’t go back past 90 days.

**to**

string format: date-time

<= 35 characters

Addresses made on or before then. Defaults to now.

**site**

string

<= 300 characters

Only addresses used on this site, such as staging.example.com.

## Responses

### 200

The list

Media typeapplication/json

### object

**from**

required

The start used: no earlier than kept\_from.

string format: date-time

**to**

required

string format: date-time

**kept\_from**

required

The earliest from can be: 90 days ago.

string format: date-time

**count**

required

How many addresses matched, including any left out.

integer

**truncated**

required

More than 5,000 matched: narrow the range or give site.

boolean

**mail\_domains**

required

The domains every test address ends in.

Array<string>

**addresses**

required

Array<object>

### object

**address**

required

string

**created\_at**

required

string format: date-time

**status**

required

string

Allowed values: live expired deleted

**ended\_at**

When it expired or was deleted.

string format: date-time

**site**

The host it was used on.

string

**environment**

string

**had\_email**

required

Whether any email reached it: if so, the app very likely has a user for it.

boolean

#### Example 

```json
{
  "addresses": [
    {
      "status": "live"
    }
  ]
}
```

### 400

An error

Media typeapplication/json

### object

**error**

What went wrong, as a code, such as bad\_request (400), unauthorized (401), plan\_required (402), forbidden (403), not\_found (404), method\_not\_allowed (405), conflict (409), content\_too\_large (413), rate\_limited, daily\_limit or account\_held (429), or server\_error (500).

string

**message**

What went wrong and what to do, in words.

string

#### Example generated

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

### 401

No API key, or one that isn’t valid: it may have been revoked, or its creator no longer has access to the project.

Media typeapplication/json

### object

**error**

What went wrong, as a code, such as bad\_request (400), unauthorized (401), plan\_required (402), forbidden (403), not\_found (404), method\_not\_allowed (405), conflict (409), content\_too\_large (413), rate\_limited, daily\_limit or account\_held (429), or server\_error (500).

string

**message**

What went wrong and what to do, in words.

string

#### Example generated

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

#### Headers

**WWW-Authenticate**

string

`Bearer realm="proxymail-qa"`, with `error="invalid_token"` when a key was sent but isn’t valid.

### 429

Too many requests. With a Retry-After header, a per-minute limit was reached: the key’s requests (60 a minute on Free, 600 on Team), password reveals (30 a minute per person), or keys that aren’t valid from one network (120 a minute). Without one, `error` says which longer limit: `daily_limit`, the space’s new addresses for today (50 on Free), until midnight UTC; `account_held`, 10 addresses a day while a Free account’s recent use is looked at; or `rate_limited` when something is full, such as a project’s 50 custom fields.

Media typeapplication/json

### object

**error**

What went wrong, as a code, such as bad\_request (400), unauthorized (401), plan\_required (402), forbidden (403), not\_found (404), method\_not\_allowed (405), conflict (409), content\_too\_large (413), rate\_limited, daily\_limit or account\_held (429), or server\_error (500).

string

**message**

What went wrong and what to do, in words.

string

#### Example generated

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

#### Headers

**Retry-After**

integer

\>= 1

Seconds to wait before trying again. Sent with per-minute limits only.

[Previous](https://proxymail.qa/docs/reference/operations/namevariants.html): Awkward names for a sign-up form's name field

[Next](https://proxymail.qa/docs/reference/operations/flowchecks.html): Checks for a sign-up, password reset or magic-link flow
