Email verification is often implemented as two operations: create a token, then consume it when a user clicks a link. That model misses a common backend reality. The same request can be retried by a client, a worker can deliver the same message twice, and two browser tabs can submit one verification link at nearly the same time.
An idempotency ledger makes these cases explicit. It records what a request tried to do, what token state existed, and which response the client should receive on a retry. The result is a REST API that is easier to operate and a PostgreSQL schema that can enforce the important parts of the contract.
Why email verification needs an idempotency contract
There are two different forms of duplication:
Request duplication: the client repeats POST /v1/email-verifications with the same intent because of a timeout.
Token duplication: two consumers present the same verification token.
They should not be solved with the same flag.…