A Small State Machine for Reliable Email Automation

Description and use

A small state machine turns flaky email tests into traceable, retry‑safe workflows with explicit states and cleanup.

Problem

Email-driven workflows become flaky due to timing issues, retries, and mailbox ownership conflicts, leading to vague errors like “verification email not found.”

Outcome

Flaky email tests become deterministic; retries are safe; logs clearly show which run owns a message and why a transition failed.

Workflow

• Assign a unique run_id and mailbox to the test run
• Set state to Reserved and lease the mailbox
• Trigger the application action that should send an email and set state to Triggered
• Poll for the expected email using bounded intervals (e.g., 1,2,4,8 s) and transition to Observed when matched
• Consume the email (click link/token) and transition to Consumed
• Release the mailbox and clean up data, transitioning to Released
• Log every state transition with event ID, timestamp, and run_id for debugging

Evidence

A small state machine gives the workflow a memory and makes these failures much easier to reason about.

Source

The five-state model is enough for many staging and end-to-end tests: Reserved, Triggered, Observed, Consumed, Released.

Source

Use bounded polling instead of one long sleep. For example, check after 1, 2, 4, and 8 seconds, then record a timeout with the last known state.

Source