Skip to content

A sign-up form spec says what your form asks for, screen by screen: each field’s section from the field catalogue, its label, whether it’s required, and its test id. Build one in the app, or with your coding agent from what you describe or from a screenshot of your form, and save it to the project. Saving uses the custom fields that already fill its fields and makes the ones it needs where nothing does, so form_values fills every field it safely can and leaves the rest for your test.

A project keeps up to 20 sign-up forms.

Ask your agent to run the build_signup_form_from_screenshot prompt, then share a screenshot of each screen of your form. It reads the fields, shows you the spec as a table to correct, and saves it only once you say yes.

The screenshots stay with your agent: only the spec you agree to is sent to Proxy Mail QA.

You can also describe the form instead: “email, password, company size and the terms box, then a second screen with your role”.

Open Project settings → Forms and choose New form. Begin from a starter or a blank form, then:

  • Add fields to each screen from the catalogue, change their labels, and mark them required or not
  • Set a field’s options under its options button: the password’s length and the characters it needs, a minimum age, a country, or the choices a drop-down offers
  • Add screens, each with its heading and page path
  • See it under Preview, its code under Code and its tests under Test, each with Copy

Labels you leave empty follow the form’s language. Each field says how it’s filled: by Proxy Mail QA, by a ready-made custom field, or by your test. Once the form is saved, a field filled by a custom field names it, with Open to go to it in Project settings → Custom fields, and says when that custom field is off. A field that one of your Standard fields switches turns off says so, with a button to them. A phone, ID or tax number field, a choice or the terms box is filled by a ready-made field: the one the form makes, by its test ID, or the project’s own for that kind of field. A phone field says when your test types it: the project’s Phone number puts in a number set aside for fiction in the UK, Australia, the US and Canada, or your app’s test number for another country, and leaves it empty for a country with neither.

In Custom fields, each custom field a form made has a From tag with the form’s name, which opens the form. One of your own that a form uses as it is has a Used by tag.

A form describes your sign-up page: its screens, fields, labels and test ids, for its code, tests and preview. Custom fields decide what goes in a field on every fill, whether or not there’s a form. A form never needs a second custom field for the same field:

  • It uses what’s there. Where one of your custom fields already fills a field, such as the project’s ready-made Phone number or your own rule for a company size question, saving uses it. It makes a ready-made one only where nothing fills the field.
  • It never beats yours silently. If a ready-made field the form made wins over one of your own custom fields (say you added your own rule after saving the form), the form says so above its fields and at the field: Keep yours removes the form’s when you save; Use the form’s keeps the form’s and isn’t asked again. In Custom fields, your field has a Clashes with tag that opens the form at that field.
  • Saving tidies up. When the form no longer uses a custom field it made, because you removed its field, changed its test id, or chose yours, saving asks first: move it to the new test id, remove it, or keep it. Where only leads change custom fields, a member asks the leads to remove it.

Your agent does the same with save_signup_form: the answer’s fields_filled_by says what fills each field, and clashes and leftovers wait for you to decide. Your agent asks you, then saves again with choices or tidy. Nothing is removed until then.

For a question of your own that one of your custom fields already answers, such as how many seats a team needs, add it from Add a field → Your custom fields. The form puts the field in its code, tests and preview; your custom field goes on deciding what goes in it on every fill. The field takes the custom field’s name and, where the custom field finds fields by test id, that test id; choose whether it’s a text box, a drop-down or a tick box. The field says whether your custom field finds it, and if a new label or test id means it doesn’t, what the custom field looks for.

Your agent adds one with section custom, the custom field’s id from list_custom_fields, a label and options.type; finds in fields_filled_by says whether the custom field finds it. A ready-made field isn’t added this way: use its field’s own section.

Have screenshots? Copy prompt gives a line to paste into your coding agent with them: your agent reads them, and they never come to Proxy Mail QA. Open in opens Qoder, Cursor, VS Code (1.140 or later) or Claude with the line already typed in: add your screenshots there, then send it. Nothing is sent until you do. If you connected Proxy Mail QA to this project from one of them, it gets a button of its own, such as Open in Qoder.

Start from one of eight specs instead of a blank form. Your agent lists them with list_signup_starters, and New form in the app offers them.

Starter What it asks for
b2c A consumer app: name, email, password, date of birth, the terms and an optional marketing box
b2b B2B SaaS: an account first, then the company’s name, website, role, team size, country, VAT and company number
education A neutral age question (the date of birth, not “Are you over 13?”) and a parent’s email for younger learners
marketplace A seller’s account, then their business: type, country, address, date of birth, tax number and payout account
travel The passenger details airlines send ahead (APIS), with a passport of Utopia, ICAO’s fictional state, and its expiry date
fintech What an identity check needs, for the US: legal name, date of birth, phone, address and a national ID number
japan A Japanese form: family name first, the reading in katakana, then email, password, date of birth, phone and address
china A Chinese form: phone first, then password, full name and the resident ID number for the real-name rule

Each comes with notes, such as where Sign in with Google or LINE buttons go (they aren’t fields) and which values come from a payment provider’s test mode. Ask for one in another language or country, and its labels, drop-downs and ID formats follow. Nothing is saved until you save your version.

For a fintech form, pair the starter with KYC sandbox mode: form_values with kyc_sandbox gives a vendor’s own sandbox values (Stripe, Plaid, Onfido, Veriff, Didit, Cashfree or Setu) for a pass, a fail or a review, and the new address it makes takes the vendor’s names and date of birth. Proxy Mail QA never checks an identity: the values only match what each vendor’s sandbox expects. See Field formats by country.

{
"name": "Main sign-up",
"site": "https://staging.example.com/*",
"language": "en",
"screens": [
{
"path": "/signup",
"fields": [
{ "section": "email" },
{ "section": "password", "options": { "min_length": 12, "classes": ["upper", "digit"] } },
{ "section": "business.team_size", "options": { "choices": ["1-10", "11-50", "51-200"] } },
{ "section": "consent.terms" }
]
}
]
}
Part What it says
name What the form is called. Saving a form with the same name changes it
site The site it’s on, as the project lists it. Leave it out to match the form’s fields on every site
language The form’s language, for its default labels: en, de, fr, es, it, pt, nl, zh or ja
country A two-letter country code for the fields that depend on one: IDs, VAT numbers, phones and addresses
screens Up to 10 screens in order, each with an optional title, path and up to 30 fields; 60 fields in all
A field Its section, required (true unless you say otherwise), label, testid and options; each section once

A field’s label defaults to its section’s label in the form’s language, and its test id to signup- and the section id with dashes, such as signup-business-team-size.

A field with section custom names one of your custom fields instead, such as { "section": "custom", "custom_field": "<its id>", "label": "Seats", "options": { "type": "select", "choices": ["1-5", "6-20"] } }. It needs a label, and its test id defaults to signup- and the label with dashes, such as signup-seats.

Options are only for the sections that take them: min_length, max_length and classes (lower, upper, digit, symbol) for a password, min_age for a date of birth, country for a country-dependent field, and choices for a drop-down or radio group.

get_signup_form and GET /v1/project/signup-forms/{id} say how each field gets its value:

Fill Meaning
built_in form_values and Proxy Mail QA for Chrome fill it from the test person: names, email, password
custom_field A custom field fills it: a ready-made one, or for section custom the one the field names
never Proxy Mail QA leaves it for your test

Only the custom_field sections get a custom field, a ready-made one: phone, ID and tax numbers, gender, language, how someone heard about you, role, team size, business type and the terms box. A form uses the project’s own ready-made ones where it has them, such as the ID and tax number fields a lead adds in Project settings → Custom fields, or all five at once with update_project’s fill_id_fields. Each one a form makes finds its field by the test id, so add those data-testid attributes to your form. Removing a form keeps its custom fields unless you ask for them to go too: in the app, Also remove the custom fields it made is ticked in the Remove dialog; agents and the API send remove_custom_fields. A custom field another form still uses stays. Where only leads change custom fields, a member’s removal asks the leads to remove them instead (Also ask the leads to remove the custom fields it made), one request for each, which they answer in Project settings → Custom fields. Otherwise, a custom field someone else added stays.

Your agent can turn a saved form into code for your app with get_signup_form_code, in one of three kinds:

Format What you get
react-hook-form A React component with react-hook-form and a zod schema (default)
react A React component with plain state and no other packages
html One HTML page with its own script

Each field checks what the spec asks for: the password’s rules, the age on a date of birth, and an ID or VAT number’s format and check digit for its country. Messages and buttons are in the form’s language. Screens show one after another, with Next and Back. Every field keeps its data-testid, so the form’s custom fields find it.

The ID checks run in the browser to help people as they type. Check them on your server too.

Your agent fits the code to your app: your components and styles, with the test ids and rules kept. The answer’s notes say what to look at, such as a drop-down still offering our usual answers.

get_signup_form_test gives tests for a saved form, for Playwright (the default) or Cypress. Each field gets values the form should take and values it should refuse, one at a time, with every other field filled in properly:

  • Left empty, when the field is required
  • An email address with no @, or no dot after it
  • A password a character too short, and one without each kind of character the spec asks for
  • A date of birth for someone who turns the minimum age tomorrow, and one for someone who turned it today
  • An ID or VAT number with the wrong check digit, a character short or a letter where a digit goes
  • Names with accents and apostrophes, and phone numbers written in other ways, which the form should take

The tests make one test address with a persona and a password before they start, and delete it after. They find each field by the data-testid the code export writes, and expect a refusal to show as the field’s <test id>-error message or aria-invalid="true". Set SIGNUP_URL to the form’s page. If your form wasn’t made from the code export, check its test ids and error messages match, or change the test’s helpers.

A field where Proxy Mail QA gives no value, such as a VAT number, is named in notes: put a value your form takes in the test’s valid().

Where only leads change custom fields, a member’s save, in the app or by their agent, goes to the leads as one request for the whole form. In the app the button says Ask the leads. The form waits as a draft, which can still be read and changed. A lead approves or declines it in Project settings → Custom fields; approving saves the form and makes its custom fields together.

Where What
MCP list_signup_starters, list_signup_forms, get_signup_form, save_signup_form, delete_signup_form, get_signup_form_code, get_signup_form_test
REST API GET /v1/signup-starters, GET and POST /v1/project/signup-forms, GET and DELETE /v1/project/signup-forms/{id}, GET /v1/project/signup-forms/{id}/code and /test
npm signupStarters({ id?, language?, country? }), signupForms(), signupForm(id), saveSignupForm(spec, id?), deleteSignupForm(id, { removeCustomFields? }), signupFormCode(id, { format?, requested? }), signupFormTest(id, { framework? })
Python list_signup_starters(starter_id=None), list_signup_forms(), get_signup_form(form_id), save_signup_form(spec, form_id=None), delete_signup_form(form_id, remove_custom_fields=False), signup_form_code(form_id, format=...), signup_form_test(form_id, framework=...)