A Runbook for Email-Driven Automation

Description and use

The runbook establishes boundaries for email-driven automation by defining a run contract, leasing a mailbox, collecting evidence, and using a decision tree for retries, thereby reducing flakiness and simplifying failure diagnosis.

Problem

Email-driven automation failures are often blamed on slow email, but the real issues are missing boundaries around inputs, mailbox, observations, and cleanup.

Outcome

The runbook introduces explicit boundaries and evidence collection, turning invisible resource collisions into visible state transitions and enabling deterministic failure analysis.

Workflow

• Define a run record with run_id, scenario, mailbox_id, expected_kind, created_at, expires_at
• Attach run_id as a correlation value in headers or metadata
• Reserve a unique mailbox or enforce ownership on a shared mailbox
• Poll the mailbox with a deadline and bounded retry budget
• Observe delivery, matching, and consumption, recording each in an evidence receipt
• Classify failures using a decision tree to decide whether to retry or fail
• Cleanup or expire the mailbox after success or failure

Evidence

Email is often treated as the last step in an automation workflow. A job creates an account, triggers a notification, waits for a message, and then reports success or failure.

Source

I have found a useful mental model: every email-driven run needs a small boundary around its inputs, mailbox, observations, and cleanup.

Source

Start with a small run record. It does not need to contain the email body or a full copy of every request.

Source

At the end of every run, write a receipt that is safe to keep in CI artifacts.

Source