A Safer Mailbox Lease for CI Automation

Description and use

Implementing mailbox leases in CI eliminates flaky email tests by providing explicit ownership, timing, and cleanup, leading to more reliable automation.

Problem

Email tests become unreliable when CI pipelines treat inboxes as permanent shared resources, leading to random failures due to ownership ambiguity.

Outcome

Implementing mailbox leases reduces flaky email tests, provides clear ownership, and enables reliable cleanup, improving CI stability.

Workflow

• Create a mailbox lease record with run ID, suite, address reference, and timestamps.
• Use the lease address for email actions (signup, reset, notification).
• Poll for expected events while recording state transitions.
• On test completion or failure, run cleanup: release or expire the lease.
• Collect a compact evidence bundle (manifest, event IDs, timestamps, failure category).

Evidence

Email tests become unreliable when every pipeline treats the inbox as a permanent shared resource.

Source

A useful mental model is a mailbox lease. A CI run temporarily owns an isolated disposable address, records why it exists, and gives it back when the run ends.

Source

The lease model gives each run four simple answers: Who owns this inbox? Why was it created? How long is it valid? What happened to it?

Source

Cleanup should run from a finally path or an equivalent CI post-job hook. It must be safe to call twice.

Source