Proxy Mail QA

Stop using Gmail as the inbox for your test codes

It starts simply: a team Gmail account, plus-addresses for each test, and a script that reads the code. Months later the tests fail on Monday mornings because a token lapsed, two runs read each other's codes, and someone has to sign in by hand to fix it.

Updated

Using a real Gmail account as the test inbox works at first. These are the ways it usually breaks.

Where it breaks

  • Tokens lapse. An OAuth app whose consent screen is in Testing gets refresh tokens that expire after 7 days. The pipeline fails until someone signs in and copies a new token in.
  • Restricted scopes. Reading mail needs one of Gmail’s restricted scopes. Moving the app out of Testing can mean Google’s verification and, for some uses, a security assessment, which is a lot for a test helper.
  • One inbox for every run. Plus-addresses (qa+run123@gmail.com) give each test its own address, but every email still lands in the same mailbox. Parallel runs read each other’s codes, and a retry can pick up the code from the previous attempt.
  • Fixed waits and fragile parsing. Scripts poll with sleep, then pull the code out with a regular expression that breaks the day marketing changes the email template.
  • A person in the loop. When Google asks to confirm the sign-in, a test can’t answer. Someone with the phone has to.

One address per test instead

Proxy Mail QA gives each test its own address and inbox, then waits for the email that arrives after a given time:

TypeScript
import { ProxyMailQA } from 'proxymail-qa';

const qa = new ProxyMailQA(); // reads PROXYMAIL_QA_API_KEY
const { address } = await qa.createAddress({ label: 'sign-up test' });

const since = new Date();
// …fill in the sign-up form with `address` and submit…
const { value: code } = await qa.waitForCode(address, { since });
  • No tokens to renew. An API key doesn’t expire after a week. Keep it in your CI secrets.
  • No collisions. Each address belongs to one test, so parallel runs never see each other’s mail.
  • No regular expressions. The code or link comes back on its own, with the time it arrived.
  • No fixed sleeps. The wait returns as soon as the email arrives, and since means an older code can’t come back.

Moving over

  1. Swap the Gmail address in your sign-up step for a new address from createAddress.
  2. Replace the inbox polling and the regular expression with waitForCode or waitForLink.
  3. Remove the Gmail credentials from CI, and the job that renews the token.

The Playwright, Cypress and pytest guides show the same steps in each framework.

Try it on your next sign-up test

Free plan, no credit card. Create an address and watch the code or link arrive.

Create a free accountOpen the app

Questions

Why does my Gmail token stop working after a week?

If your Google Cloud project's OAuth consent screen is in Testing, Google expires its refresh tokens after 7 days (unless the app asks only for name, email and profile, which can't read mail). Publishing the app avoids that, but Gmail's read scopes are restricted, so a published app may need Google's verification first.

Can't I just use IMAP with an app password?

App passwords need 2-Step Verification on the account, and an organisation's Google Workspace admin can turn them off. Even when they work, every test still shares one inbox and has to pick its email out of everyone else's.

Gmail plus-addressing gives every test its own address. Isn't that enough?

It gives each test its own address, not its own inbox. Everything still lands in one mailbox, so your script has to search for the right email, and a slow email can be matched to the wrong test. Some sign-up forms also refuse + addresses.

What about a second Gmail account just for testing?

Google may block sign-ins from browsers controlled by automation software, and a new account can be asked to confirm a phone number. Either way, a person has to step in, and that one account becomes the shared inbox again.

Built your app with an AI tool? Pick yours