DEV Community

DapperX
DapperX

Posted on

A Small State Machine for Burner Email Automation

A Small State Machine for Burner Email Automation

Email verification is often the least deterministic part of an otherwise tidy test. A message can be sent, delayed, filtered, opened by the wrong run, or expire while a retry is still running. When a team treats a burner email inbox as “just a string,” failures become hard to explain and easy to repeat.

I have found a small state machine makes this problem much more approachable. It gives an Automation workflow a shared vocabulary, and it turns an ephemeral inbox into a run-scoped test fixture with clear ownership.

Why email fixtures need explicit states

An email test usually has more states than created and verified. For example, a CI job might create an address, request a verification message, poll for it, consume a token, and then clean up. A retry can enter halfway through that sequence if the previous attempt did not leave enough evidence.

That ambiguity creates familiar symptoms:

  • The poller waits forever because the message arrived before its start time.
  • A retry consumes a token created by an earlier run.
  • Cleanup deletes an inbox that another test still owns.
  • A failed build says “verification timeout” but does not show which step timed out.

The fix is not adding more retries. First, define the lifecycle and make every transition observable. This is a small piece of Developer Tools design, but it saves a surprising amount of debugging time.

The five-state model

For most email-backed tests, five states are enough:

  1. Allocated — the fixture exists and belongs to one run.
  2. Requested — the application asked for a verification email.
  3. Observed — a matching message was found and its metadata was saved.
  4. Consumed — the token or link was used successfully.
  5. Expired — the fixture reached its deadline without a valid completion.

The important rule is that transitions should be monotonic. A fixture can move from Requested to Observed, but it should not silently move back to Allocated during a retry. If a retry needs a fresh fixture, allocate a new one and keep the old record for diagnosis.

This is similar to the run ledger pattern I use for scheduled jobs. A run ledger for scheduled jobs makes ownership and replay visible; the same idea works for test inboxes.

A small implementation

The implementation does not need a framework. A record with an idempotency key, timestamps, and a state is enough to start:

from dataclasses import dataclass
from datetime import datetime
from typing import Literal

State = Literal["allocated", "requested", "observed", "consumed", "expired"]

@dataclass
class EmailFixture:
    run_id: str
    address: str
    state: State
    deadline: datetime
    message_id: str | None = None

    def can_move_to(self, next_state: State) -> bool:
        order = {
            "allocated": 0,
            "requested": 1,
            "observed": 2,
            "consumed": 3,
            "expired": 4,
        }
        return next_state == "expired" or order[next_state] == order[self.state] + 1
Enter fullscreen mode Exit fullscreen mode

In production, store the transition event as well as the current row. The event should include the run ID, request ID, observed message ID, and a reason for expiration. Do not put the verification token itself into ordinary build logs. That bit is easy to miss when debugging fast.

Your poller can then stop on a known boundary:

while fixture.state == "requested":
    if clock.now() >= fixture.deadline:
        transition(fixture, "expired", reason="message deadline exceeded")
        break
    message = inbox.find(subject="Verify your account", after=fixture.requested_at)
    if message:
        transition(fixture, "observed", message_id=message.id)
        break
    clock.sleep(2)
Enter fullscreen mode Exit fullscreen mode

Use a unique run marker in the request when possible. Subject matching alone is a weak filter, especially when a shared test environment sends several similar messages. For UI suites, the techniques in this guide to email receipts for Playwright retries are a useful companion to this state model.

What to record when a run fails

A useful failure record answers “what happened?” without requiring a rerun. I normally keep:

  • run ID and test name;
  • fixture address, provider, and allocation time;
  • requested-at and deadline timestamps;
  • current state and the last transition reason;
  • message ID, subject hash, and received-at time;
  • retry number and the parent run, if any.

The address is test data, not a secret, but it still deserves a short retention period. If a team searches for a temp gamil com workaround or a tempail lookup during an incident, that is often a sign the fixture contract is unclear, not that another provider is needed.

For a public test environment, a throwaway email address can be useful for a manual smoke check. Keep that path separate from CI assertions, document its expiry behavior, and never use it for real user data.

A practical checklist

Before calling an email test reliable, check these questions:

  1. Does every fixture have a run owner and a deadline?
  2. Can a retry distinguish its messages from an earlier attempt?
  3. Are state transitions idempotent and monotonic?
  4. Does the failure artifact include the last observed transition?
  5. Is cleanup delayed until no active child run owns the fixture?
  6. Are tokens excluded from logs and screenshots?

The goal is not to build a huge email platform. It is to give each test a small, explicit contract. Once the states are visible, the rest of the workflow becomes ordinary Automation: allocate, request, observe, consume, and expire. That mental model makes failures boring, and boring failures are exactly what we want from CI.

Top comments (0)