One-time codes delivered by email are a favorite of QA engineers because they sit at the intersection of HTTP and email. The API sends the code, the inbox receives it, and the API verifies it. Testing this without a real inbox means mocking away the very step you are trying to prove, so a disposable inbox is the better tool.
What Makes Code Verification Different
Unlike a click-through link, a verification code is a value the user must read and type. That introduces states the API layer has to enforce, and each one deserves a test:
- A code that is valid and unused should succeed.
- A code that has already been consumed should fail.
- An expired code should fail.
- A wrong or malformed code should fail.
- A code requested for one address should not work for another.
Covering these cases, plus the happy path, gives real confidence in the mechanism rather than just the endpoint.
Request, Retrieve, Verify
The API side is straightforward: call an endpoint to send a code, then use the inbox to retrieve it. With Mail4QA you direct a message to an address and it appears; there is nothing to register, which keeps the test setup minimal. Check exact routes in the public mailbox API docs.
import requests
import time
BASE = "https://mail4qa.com/api/public/v1"
def request_code(address):
# Trigger the application's send-code endpoint
r = requests.post("https://app.example.com/api/send-code", json={"email": address})
r.raise_for_status()
def fetch_code(address, timeout=20):
deadline = time.time() + timeout
while time.time() < deadline:
msgs = requests.get(f"{BASE}/inbox/{address}/messages").json()
for m in msgs:
code = extract_code(m["body"])
if code:
return code
time.sleep(1)
raise TimeoutError(f"No code for {address}")
The extract_code helper should match the exact format the application uses. A six-digit numeric code and a longer alphanumeric token need different patterns, so keep the pattern next to the assumption it encodes.
Poll With a Deadline
As with any asynchronous step, poll on a fixed interval and stop at a deadline. A code that never arrives should fail the test with a clear message, not hang the suite until CI times out.
Verify Through the API
Type nothing by hand. Post the code back to the verification endpoint and assert the response.
def verify(address, code):
return requests.post(
"https://app.example.com/api/verify-code",
json={"email": address, "code": code},
)
def test_valid_code_succeeds(address):
request_code(address)
code = fetch_code(address)
assert verify(address, code).status_code == 200
def test_reused_code_fails(address):
request_code(address)
code = fetch_code(address)
verify(address, code)
assert verify(address, code).status_code != 200
Covering the Negative Cases
Negative tests are where API-level code testing earns its keep. They are cheap to run and catch issues that a happy-path UI test never will.
- Reuse: submit the same code twice and confirm the second attempt is rejected.
- Expiry: if the API supports a short TTL, wait past it and assert rejection.
- Mismatch: request a code for one address, then attempt it against a different address in the same environment.
- Format: send an obviously malformed value and confirm a clean error instead of a server fault.
- Rate limits: request codes repeatedly and confirm throttling behaves as designed.
Watch the Error Surface
A correct rejection returns a well-defined error and status code. Assert on both, because a 200 with an error body is just as much a bug as a 500. This is where API testing gives you a sharper view than a browser test ever could.
Keeping Tests Independent
Every test should own its address so runs can happen in parallel. Use a random or timestamped local part, and delete the inbox when the test ends. Capture the code and any relevant headers in the failure output so debugging a missing or malformed message does not require a rerun.
For exploring payloads during development, the Public Inbox shows what a real message looks like before you write assertions. Seeing the structure once makes the extraction pattern obvious.
Conclusion
Email verification codes are an API problem first and a UI problem second, so test them at the API layer with a disposable inbox. Request the code, retrieve it programmatically, and verify it through the same endpoint the client uses, then add the reuse, expiry, and mismatch cases. That mix gives you strong, fast coverage of the mechanism without touching a shared mailbox.
