---
title: "Add a site | 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/addsite
---

# Add a site

POST

/v1/project/sites

```js
const url = 'https://api.proxymail.qa/v1/project/sites';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"site":"staging.acme.dev","environment":"staging"}'
};

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/project/sites \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "site": "staging.acme.dev", "environment": "staging" }'
```

Adds a site to the project’s list, as Project settings → Sites → Add site does: one host and every page of it, or a page’s address on it (`localhost:3000` adds `http://localhost/*`, every port). Only a host that doesn’t look live: a local server, or a host with a test word in it such as staging, dev, qa, preview or sandbox, and never the environment `production`. A host that looks live is refused (403) with a link that opens Add a site in the app, where a person confirms it’s a test site. A `*` is refused. 201 when it’s added, 200 when it was listed already (`status: "listed"`, left as it is). On a locked project, a key whose creator isn’t a lead asks the leads instead (202, `status: "requested"`). It never gives Chrome access: each person gives that once, from Proxy Mail QA for Chrome’s popup on the site. Sites are removed only in the app.

## Authorizations

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

## Request Bodyrequired

Media typeapplication/json

### object

**site**

required

A host or a page’s address, such as staging.acme.dev or localhost:3000\. No `*`.

string

<= 300 characters

### Example 

```plaintext
staging.acme.dev
```

**environment**

required

Such as staging, qa, dev, preview or local.

string

<= 40 characters

### Example 

```plaintext
staging
```

## Responses

### 200

Listed already

Media typeapplication/json

### object

**status**

Listed: it was on the list already and is left as it is. requested: the project is locked, so a lead was asked.

string

Allowed values: saved listed requested

**site**

### object

**id**

string format: uuid

**pattern**

string

**environment**

string

**multi\_step**

Sign-up goes over several screens: Proxy Mail QA for Chrome 0.9.0 and later fills each later screen of a sign-up on this site by itself.

boolean

**screens**

Array<object>

One screen a site’s sign-up goes over: a page’s path, or a native app screen’s name.

### object

**id**

string format: uuid

**site\_id**

Null for one of the app screens, which have no site.

string | null format: uuid

**kind**

string

Allowed values: path native

**value**

The page’s path, or the native app screen’s name.

string

**label**

A short name people recognise.

string | null

**status**

Suggested: added by a fill or form-values, or waiting for a lead, and not kept yet.

string

Allowed values: kept suggested

**origin**

string

Allowed values: added filled form\_values

**step**

Which screen of the sign-up it was, when known.

integer | null

**created\_via**

string

Allowed values: app extension agent api

**agent\_name**

string | null

**created\_at**

string format: date-time

**kept\_at**

string | null format: date-time

**last\_seen\_at**

string | null format: date-time

**request**

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

### object

**id**

required

string format: uuid

**kind**

required

string

Allowed values: save\_custom\_field delete\_custom\_field add\_site remove\_site set\_guesses set\_multi\_step save\_signup\_screen remove\_signup\_screen set\_custom\_field\_enabled set\_standard\_field save\_signup\_form

**target\_id**

required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid

**summary**

required

The custom field’s name, the site, the screen, or the setting’s new choice.

string

**change**

required

What it changes, as it applies once a lead approves it.

### object

**note**

required

What the person who asked wrote for the leads.

string | null

**status**

required

string

Allowed values: requested approved declined withdrawn expired unlocked

**reason**

required

A lead’s reason for declining.

string | null

#### Example 

```json
{
  "status": "saved",
  "site": {
    "pattern": "https://staging.acme.dev/*",
    "environment": "staging",
    "screens": [
      {
        "kind": "path",
        "value": "/signup/team",
        "label": "Team details",
        "status": "kept",
        "origin": "added",
        "created_via": "app"
      }
    ]
  },
  "request": {
    "kind": "save_custom_field",
    "status": "requested"
  }
}
```

### 201

Added

Media typeapplication/json

### object

**status**

Listed: it was on the list already and is left as it is. requested: the project is locked, so a lead was asked.

string

Allowed values: saved listed requested

**site**

### object

**id**

string format: uuid

**pattern**

string

**environment**

string

**multi\_step**

Sign-up goes over several screens: Proxy Mail QA for Chrome 0.9.0 and later fills each later screen of a sign-up on this site by itself.

boolean

**screens**

Array<object>

One screen a site’s sign-up goes over: a page’s path, or a native app screen’s name.

### object

**id**

string format: uuid

**site\_id**

Null for one of the app screens, which have no site.

string | null format: uuid

**kind**

string

Allowed values: path native

**value**

The page’s path, or the native app screen’s name.

string

**label**

A short name people recognise.

string | null

**status**

Suggested: added by a fill or form-values, or waiting for a lead, and not kept yet.

string

Allowed values: kept suggested

**origin**

string

Allowed values: added filled form\_values

**step**

Which screen of the sign-up it was, when known.

integer | null

**created\_via**

string

Allowed values: app extension agent api

**agent\_name**

string | null

**created\_at**

string format: date-time

**kept\_at**

string | null format: date-time

**last\_seen\_at**

string | null format: date-time

**request**

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

### object

**id**

required

string format: uuid

**kind**

required

string

Allowed values: save\_custom\_field delete\_custom\_field add\_site remove\_site set\_guesses set\_multi\_step save\_signup\_screen remove\_signup\_screen set\_custom\_field\_enabled set\_standard\_field save\_signup\_form

**target\_id**

required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid

**summary**

required

The custom field’s name, the site, the screen, or the setting’s new choice.

string

**change**

required

What it changes, as it applies once a lead approves it.

### object

**note**

required

What the person who asked wrote for the leads.

string | null

**status**

required

string

Allowed values: requested approved declined withdrawn expired unlocked

**reason**

required

A lead’s reason for declining.

string | null

#### Example 

```json
{
  "status": "saved",
  "site": {
    "pattern": "https://staging.acme.dev/*",
    "environment": "staging",
    "screens": [
      {
        "kind": "path",
        "value": "/signup/team",
        "label": "Team details",
        "status": "kept",
        "origin": "added",
        "created_via": "app"
      }
    ]
  },
  "request": {
    "kind": "save_custom_field",
    "status": "requested"
  }
}
```

### 202

Asked a lead

Media typeapplication/json

### object

**status**

Listed: it was on the list already and is left as it is. requested: the project is locked, so a lead was asked.

string

Allowed values: saved listed requested

**site**

### object

**id**

string format: uuid

**pattern**

string

**environment**

string

**multi\_step**

Sign-up goes over several screens: Proxy Mail QA for Chrome 0.9.0 and later fills each later screen of a sign-up on this site by itself.

boolean

**screens**

Array<object>

One screen a site’s sign-up goes over: a page’s path, or a native app screen’s name.

### object

**id**

string format: uuid

**site\_id**

Null for one of the app screens, which have no site.

string | null format: uuid

**kind**

string

Allowed values: path native

**value**

The page’s path, or the native app screen’s name.

string

**label**

A short name people recognise.

string | null

**status**

Suggested: added by a fill or form-values, or waiting for a lead, and not kept yet.

string

Allowed values: kept suggested

**origin**

string

Allowed values: added filled form\_values

**step**

Which screen of the sign-up it was, when known.

integer | null

**created\_via**

string

Allowed values: app extension agent api

**agent\_name**

string | null

**created\_at**

string format: date-time

**kept\_at**

string | null format: date-time

**last\_seen\_at**

string | null format: date-time

**request**

A request to the project’s leads, who approve or decline it in Project settings. Who asked and answered, and when, are in the app.

### object

**id**

required

string format: uuid

**kind**

required

string

Allowed values: save\_custom\_field delete\_custom\_field add\_site remove\_site set\_guesses set\_multi\_step save\_signup\_screen remove\_signup\_screen set\_custom\_field\_enabled set\_standard\_field save\_signup\_form

**target\_id**

required

The custom field, site, sign-up screen or sign-up form it changes, if any.

string | null format: uuid

**summary**

required

The custom field’s name, the site, the screen, or the setting’s new choice.

string

**change**

required

What it changes, as it applies once a lead approves it.

### object

**note**

required

What the person who asked wrote for the leads.

string | null

**status**

required

string

Allowed values: requested approved declined withdrawn expired unlocked

**reason**

required

A lead’s reason for declining.

string | null

#### Example 

```json
{
  "status": "saved",
  "site": {
    "pattern": "https://staging.acme.dev/*",
    "environment": "staging",
    "screens": [
      {
        "kind": "path",
        "value": "/signup/team",
        "label": "Team details",
        "status": "kept",
        "origin": "added",
        "created_via": "app"
      }
    ]
  },
  "request": {
    "kind": "save_custom_field",
    "status": "requested"
  }
}
```

### 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.

### 403

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

### 405

The path doesn’t take this method.

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

**Allow**

string

The methods it takes, such as `GET, PATCH`.

### 413

The request body is over 64 KB, or 256 KB for POST /v1/form-values.

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

### 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/listsites.html): The project's sites and their sign-up screens

[Next](https://proxymail.qa/docs/reference/operations/setmultistep.html): Turn filling each screen on or off
