Guides → Testing email signup flows
How to test email signup and verification flows
Signup email is the one flow every product has and almost nobody tests properly. It usually gets checked once by hand, from one mailbox, on one email client — and then breaks silently six months later when a template changes.
What actually needs testing
Most teams verify that a confirmation email arrives and stop there. The failures that reach production are usually elsewhere:
- Does the code expire when it should? Wait past the window and confirm it is rejected.
- Does requesting a second code invalidate the first? A surprising number of implementations leave both valid, which is a real security issue.
- Is the code rate-limited? Ten requests in ten seconds should not send ten emails.
- What happens on re-registration with an existing address? Leaking whether an address exists is a common privacy bug.
- Are the links absolute and correctly domained? Staging URLs escaping into production email is a classic.
- Does it survive a plus-address, a long local part, or a non-ASCII domain?
- Is the mail still sent if the user closes the tab immediately? Catches flows that queue on the client rather than the server.
Why a real mailbox is the wrong tool
Testing from your own Gmail breaks down fast. You need a genuinely fresh address per run to test the new-user path, providers throttle repeated signups from one mailbox, and you cannot poll a personal inbox from CI without handing credentials to your test runner. Within a week you have four hundred test emails in a mailbox you actually use.
The disposable-inbox approach
Generate an address per test run, submit it, then poll for the message programmatically. The whole cycle takes seconds and leaves nothing behind. In broad strokes:
- Request a fresh address from the service's API.
- Drive your signup form with it.
- Poll the inbox until the message arrives, with a sensible timeout.
- Extract the code or confirmation link from the body.
- Complete the flow and assert the account reached the state you expect.
- Repeat for the negative cases: expired code, reused code, wrong code.
PHMail exposes this through its developer API, which is the use case it was built for.
Things worth getting right
Poll with a timeout and a clear failure message. A test that hangs for two minutes and then says "assertion failed" tells you nothing. Say what you were waiting for.
Do not assert on exact copy. Marketing will change the subject line, and your test should not break because of it. Assert on structure and on the code pattern.
Use a distinct address per test, not per suite. Shared addresses cause tests to read each other's mail and fail intermittently, which is the worst kind of failure to debug.
Test the rejection path too. Many production sites block disposable domains. If yours does, confirm that block works — and use a different mechanism for the tests that need to get through it.
The limit of this approach
A disposable inbox proves the message was sent and what it contained. It says nothing about deliverability to real users — whether you land in spam at a major provider, whether your SPF, DKIM and DMARC records are correct, or how the template renders in Outlook. Those need dedicated tooling. Getting green tests here is necessary, not sufficient.