A practical design for email verification endpoints that remain explainable when retries, delayed messages, and support questions arrive together.
Email verification looks like a small authentication feature until a production incident asks a simple question: why was this account still unverified after the user clicked the link?
The answer is often spread across an API log, a message provider, a worker queue, and a database row. When each component has a slightly different idea of the current state, the endpoint may work in the happy path but become difficult to operate. My preferred approach is to make the verification workflow an explicit, auditable boundary in the backend.
Why verification APIs become hard to audit
Most implementations begin with three actions:
Create a verification token.
Send an email containing the token.
Mark the user as verified when the token is opened.
The hidden complexity is in the transitions between those actions. A client can retry the create request.…