# How to Test OTP and Verification Code Emails in Staging

> Test one-time-password emails reliably: use throwaway inboxes, check expiry and attempt limits, avoid leaking codes, and automate the flow in end-to-end tests.

Published 2026-11-19. Source: https://mailions.com/blog/test-otp-emails-staging

One-time passwords by email are small messages with a big job. If the code does not arrive in seconds, users abandon the sign-up. If a code works twice, or never expires, you have a security hole. Both are easy to miss when you only test the happy path by hand.

This guide shows how to test an OTP email flow end to end in a staging environment. If you are building the flow itself, start with [how to send OTP emails](/blog/send-otp-email).

## What an OTP flow must guarantee

Write these down as test cases before you start. A safe flow:

| Property | Typical value |
|---|---|
| Code is random and unpredictable | Cryptographically random, 6 to 8 digits |
| Code expires | 5 to 10 minutes |
| Code works once | Used code is rejected |
| Wrong attempts are limited | Around 5 tries, then a new code is needed |
| Sending is rate limited | For example one email per minute per address |
| Only a hash is stored | The code itself is not saved in plain text |
| A new code replaces the old | Previous codes stop working |

## Step 1: Give every test run its own inbox

Test runs interfere with each other if they share an address. Generate a unique address per test, for example:

```js
const inbox = `otp-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
const email = `${inbox}@temp.example.com`;
```

Use the domain of a public temporary inbox service so you can read the result without credentials. Remember that anyone who knows or guesses the name can read the message, so use staging accounts and throwaway data only. See [what a temporary email address is](/blog/what-is-temporary-email).

## Step 2: Trigger and read the message

An end-to-end test with Playwright looks like this in outline:

```js
await page.goto('/login');
await page.fill('#email', email);
await page.click('text=Send code');

// Poll the inbox page with a deadline, not forever.
const code = await waitForCode(inbox, { timeoutMs: 30000 });

await page.fill('#code', code);
await page.click('text=Verify');
await expect(page).toHaveURL(/dashboard/);
```

`waitForCode` fetches the inbox page, finds the newest message, and extracts the digits with a regular expression such as `/\b(\d{6})\b/`. Keep the wait generous but bounded, retry a few times at a moderate interval, and fail with the inbox contents in the error so you can see what arrived.

## Step 3: Test the failure paths

Each of these deserves its own test:

1. **Wrong code.** The page shows an error and the attempt counter increases.
2. **Too many wrong codes.** After the limit, even the right code is rejected until a new one is requested.
3. **Expired code.** Fast-forward your app's clock or set a short expiry in staging, then confirm rejection.
4. **Reused code.** The same code twice must fail the second time.
5. **Resend too quickly.** The rate limit message appears and no second email is sent.
6. **Resend after the window.** A new email arrives, and the old code stops working.
7. **Unknown address.** The response looks the same as for a known address, so the form cannot be used to discover accounts.

## Step 4: Check the email itself

Open the message and look at more than the digits:

- The code is easy to read and select, preferably on its own line in large type.
- The subject does not contain the code if your policy treats subjects as less private (many apps put it there for convenience; decide deliberately).
- The expiry time is stated in the text.
- There is a line telling the recipient to ignore the message if they did not request it.
- The plain-text version has the code.
- The sender is on your authenticated domain, and the headers show passing SPF, DKIM and DMARC ([how to check](/blog/check-spf-dkim-dmarc)).

## Step 5: Check timing

Time the whole path: button click to message visible. For OTPs, arrival within a few seconds is the goal. If it regularly takes longer, look at your queue, your relay and your sending reputation. Remember that a message the relay accepted is not yet in the inbox.

## Things that make OTP tests flaky

- **Sharing an inbox between tests,** so one test reads another's code.
- **Fixed sleeps** instead of waiting for the message.
- **Parsing the wrong number,** such as a year or a phone number in the footer. Anchor your pattern on a label.
- **Staging sending to a real provider with strict limits.**
- **Time zones and clock drift** in expiry checks.

## Security notes

- Never log OTP codes in production. In staging logs, remember that others may read them.
- Do not expose a "debug" endpoint that returns the code, and make sure test shortcuts cannot be switched on in production.
- A fixed code such as `000000` for test accounts is a risk if it can ever reach production. Gate it with a configuration that the production environment cannot enable.

## Doing it with Mailions

Send your OTP email through the Mailions [sending API](/help/sending-api) from your staging environment, using a verified domain and an `Idempotency-Key` so a retry cannot produce two codes in the inbox. Read the result at [/temp](/temp), where new messages appear live without refreshing, and use the panel's sending log to confirm what the relay did with each message.

## Frequently asked questions

### How do I test OTP emails automatically?

Give each test run its own inbox address, trigger the code, read the newest message in that inbox and extract the code with a pattern. Then test expiry, wrong codes and resends, not only the happy path.

### Why are my OTP email tests flaky?

Usually because tests share an inbox and read another run's message, pick up an older code, or wait a fixed time instead of waiting for the message to arrive. Unique addresses and checking for mail newer than the trigger fix most cases.

### Is it safe to use a public temporary inbox for OTP tests?

Only for test accounts with no real data. Anyone who knows the address can read a public inbox, so never use one for production accounts, customer data or anything you would not publish.
