Retryable Email Automation Needs a State Contract

说明与用途

在邮件自动化中实现状态合同，使重试安全且可解释，消除重复账户和不透明错误。

问题

Retries in email automation often fail silently, creating duplicate accounts or consuming wrong verification emails, making failure diagnosis hard.

结果

Implementing a state contract for email automation makes retries safe, observable, and debuggable, reducing flaky tests and clarifying failure causes.

工作流

• Generate a unique run_id and mailbox_id
• Create run record with state "created"
• Trigger verification request with run_id embedded in email
• Set state to "requested" and record requested_at
• Poll inbox for message matching run_id, recipient, sender, and time window
• If message found, move state to "received" and record message_id
• If message not found within deadline, move state to "failed" with reason "delivery_timeout"
• On retry, increment attempt counter and ensure atomic token transition if applicable
• Use state.move to validate allowed transitions
• Log concise events for each state change
• Apply failure triage checklist to diagnose issues

证据

A worker should not decide to retry because a generic exception occurred. It should retry because the current state is known to be temporary and the operation is safe to repeat.

来源

For an email-driven workflow, useful states might be: created, requested, waiting, received, verified, expired, failed.

来源

The polling loop can stay boring. That is a feature.

来源

When a job fails, check these facts in order: Was the run ID generated once and reused for every request?

来源