Skip to content
POST
/v1/addresses/{address}/submits
curl --request POST \
--url https://api.proxymail.qa/v1/addresses/k7f2x9ab12cd%40mailclub.dev/submits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Proxy-Mail-QA-Test: sign-up%20%E2%80%BA%20sends%20one%20code' \
--data '{ "flow": "sign_up", "site": "https://staging.example.com/sign-up" }'

Records that the test is about to submit a form with this address: a sign-up (sign_up, the default), sign_in, reset or magic_link form, on site (kept as host and path, with any part of the path that has an email address, an ID, a long number or a token in it hidden; never the query or fragment). Call it just before the test presses the button and pass submitted_at as the wait’s since: the time is ours, so a test machine’s clock can’t skew it, and it’s taken when the call arrives, so after the click a fast email can come first. The /code or /link wait that finds its code or link then returns time_to_email. Never send the form’s contents. With a run, the report says the form was sent and how long each email took after it. Up to 120 an hour per address.

address
required
string format: email
<= 254 characters

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
Proxy-Mail-QA-Run
string format: uuid
<= 36 characters

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

sign-up%20%E2%80%BA%20sends%20one%20code
Media typeapplication/json
object
flow
string
default: sign_up
Allowed values: sign_up sign_in reset magic_link other
site

The page the form is on. Kept as host and path, with any part of the path that has an email address, an ID, a long number or a token in it hidden; never the query or fragment.

string
<= 2000 characters

Example

https://staging.example.com/sign-up

The submit, as stored

Media typeapplication/json
object
id
string format: uuid
address
string
flow
string
site
string | null
submitted_at
string format: date-time

Example

{
"site": "staging.example.com/sign-up"
}

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