Skip to content
POST
/v1/project/sites
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.

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

staging.acme.dev
environment
required

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

string
<= 40 characters

Example

staging

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

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

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

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

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

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

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

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

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

{
"error": "example",
"message": "example"
}
WWW-Authenticate
string

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

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

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

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

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

The methods it takes, such as GET, PATCH.

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

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

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

{
"error": "example",
"message": "example"
}
Retry-After
integer
>= 1

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