Retryable Email Automation Needs a State Contract

Описание и применение

Внедрение контракта состояния в автоматизацию email делает повторные попытки безопасными и понятными, устраняя проблемы с дублированием аккаунтов и непонятными ошибками.

Задача

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?

Источник