Skip to content

The proxymail-qa package has a command, from version 0.13.0. Use it in a terminal while you test by hand, in npm scripts, in a JetBrains or VS Code run configuration, or in a CI step. It runs on Node 18 or later and needs no install beyond npx.

  1. Create an API key and set it as PROXYMAIL_QA_API_KEY. The command reads the key only from the environment, never from an option, so it stays out of your shell history.

    export PROXYMAIL_QA_API_KEY=qa_...
  2. In a terminal it shows the address, the password, and the persona’s name, username, date of birth and country, ready to type into the sign-up form. The password is saved on the address and shown only this once.

    npx proxymail-qa new --password --country JP
  3. Sign up with the address, then:

    A wait holds for 30 seconds unless you give --timeout. If nothing arrives, it says why as far as Proxy Mail QA can tell and exits with 1.

    npx proxymail-qa wait-code k7f2@mailclub.dev
    npx proxymail-qa wait-link k7f2@mailclub.dev --type reset
Command What it does
new Makes a test address with a persona. --password, --country, --age or --dob, --one-name, --label, --site, --environment, --days, --no-persona
wait-code <address> Waits for a sign-in code. --type coupon for a coupon, --since, --service, --unused, --timeout
wait-link <address> Waits for a link. --type verify, reset, magic_signin or invite (several with commas), --app for the link that opens a mobile app
persona <address> Shows the address’s persona
form-values <file> What to type in each field of a form: see below

npx proxymail-qa help <command> lists a command’s options. Add --json to any command for the whole answer as JSON.

When its output goes to a pipe or a variable, a command prints just the value: the address, the code or the link. new --password prints the address, then the password on a second line.

ADDRESS=$(npx proxymail-qa new --site staging.example.com --environment staging)
# …sign up with $ADDRESS…
CODE=$(npx proxymail-qa wait-code "$ADDRESS" --timeout 60)

The password is printed so a script can use it: keep it in a variable and don’t echo it to a CI log. In a run (PROXYMAIL_QA_RUN, which the GitHub Action sets), every call is added to the run’s report.

As npm scripts, so the team runs the same commands:

package.json
{
"scripts": {
"inbox": "proxymail-qa new --password --site localhost:3000 --environment local",
"code": "proxymail-qa wait-code"
}
}

npm run inbox, then npm run code -- k7f2@mailclub.dev. In JetBrains IDEs, add a run configuration of type npm for each script, or a Shell Script configuration that runs npx proxymail-qa new.

form-values takes a JSON file that lists a form’s fields, and answers with what to type in each one, from a new address or one you name with --address. It fills the project’s custom fields and the names, dates and passwords a form asks for, as the Node.js client’s formValues does.

signup-form.json
{
"fields": [
{ "id": "email", "type": "email", "label": "Email" },
{ "id": "name", "label": "Full name" },
{ "id": "team", "type": "select", "label": "Team size", "options": [{ "value": "1-10" }, { "value": "11-50" }] }
],
"page": "/signup"
}
npx proxymail-qa form-values signup-form.json --site staging.example.com --country PK

It prints JSON: the address, the persona, the password when one was made, and a value per field. Options on the command line win over the same ones in the file. Use - instead of a file name to read the fields from standard input.

Code Meaning
0 Done
1 The API refused, or nothing arrived in time. The reason is on standard error
2 The command was wrong, or PROXYMAIL_QA_API_KEY isn’t set