DEV Community: kevindev

Node.js Verification APIs Need a Mailbox Lease

kevindev — Wed, 14 Oct 2026 05:23:17 +0000

Email verification looks small until a service must handle retries, delayed delivery, duplicate clicks, and automated tests. The usual implementation sends a message, stores a token, and hopes the user clicks it once. That model breaks down.

I prefer treating the verification mailbox as a lease. A lease has an owner, an expiry time, a purpose, and a clear release or consumption rule. Thinking in those terms gives a Node.js REST API enough structure to behave predictably when the client retries or the email provider is slow.

Why a verification mailbox is a lease

The address used for a verification flow should be associated with one account and one attempt. It should not be a shared bucket where any recent message can satisfy any request. Otherwise a delayed message can verify the wrong session.

The lease can be represented with four values. This small contract is easy to skip during a hurried deploy, but it keeps the workflow deterministic:

lease_id: unique identifier for this verification attempt
user_id: the account that owns the attempt
expires_at: the last time the attempt may be consumed
status: pending, consumed, or expired

The disposable email generator or other test mailbox is only a delivery dependency. It is not proof that the token belongs to the current request. That proof should come from the database record and the token hash.

For CI, each run should have an isolated inbox. This makes it easier to connect a message to a test. See these low-noise CI email checks for treating email automation as an observable pipeline step.

The database contract

Do not store the raw verification token. Store a hash, just as you would store a password reset token. A compact PostgreSQL table might look like this:

CREATE TABLE email_verification_leases (
  id uuid PRIMARY KEY,
  user_id uuid NOT NULL REFERENCES users(id),
  token_hash bytea NOT NULL,
  status text NOT NULL CHECK (status IN ('pending', 'consumed', 'expired')),
  expires_at timestamptz NOT NULL,
  consumed_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX verification_leases_active_idx
  ON email_verification_leases (user_id, expires_at)
  WHERE status = 'pending';

The partial index keeps the common lookup focused on active leases. The expiry check still belongs in the query, because an index does not change the meaning of time. When creating a new lease, invalidate an older pending lease or explicitly select the current attempt.

That decision matters for retries. A second POST /verification/send should not create five valid tokens because a browser retried after a timeout. The request needs an idempotency key, or the service needs a deduplication window based on user and purpose.

A Node.js endpoint with idempotent behavior

The endpoint can accept an idempotency key and keep its side effects inside a transaction. The example leaves the mail provider behind an interface so the database decision is testable without sending a real message.

app.post('/v1/email-verification', async (req, res, next) => {
  const userId = req.auth.userId;
  const key = req.header('Idempotency-Key');

  if (!key) {
    return res.status(400).json({ error: 'idempotency_key_required' });
  }

  try {
    const result = await db.transaction(async (tx) => {
      const previous = await tx.verificationRequest.findByKey(userId, key);
      if (previous) return previous.response;

      const lease = await tx.verificationLease.createPending({
        userId,
        ttlSeconds: 900,
      });

      const response = { leaseId: lease.id, expiresAt: lease.expiresAt };
      await tx.verificationRequest.saveResponse(userId, key, response);
      await mailer.enqueueVerification(userId, lease.id);
      return response;
    });

    return res.status(202).json(result);
  } catch (error) {
    return next(error);
  }
});

In a real service, the mail enqueue operation needs an outbox record in the same transaction. Calling a provider directly before the transaction commits can produce a message for a lease that was rolled back. The outbox worker can claim unsent records, publish them, and record a delivery attempt.

The request replay behavior is worth keeping boring. The same key returns the same lease response, even if the first HTTP response was lost. These CLI guardrails for signup email checks are useful background for applying the same discipline to automated verification flows. It is occassionally tempting to just resend, but that creates a dependancy on timing.

Polling and evidence at the API boundary

Consumers should poll for a message with a stop rule, not forever. Record the lease id, inbox address, trigger time, message id, and why a message was accepted. If no message arrives before expiry, the failure should say whether delivery was late, the subject was wrong, or ownership evidence was missing.

This also prevents a common debugging shortcut: searching for phrases such as fake e mail com and then opening the newest message by hand. That can hide a routing bug while making the test appear intermittently healthy. Exact lease ownership is stronger evidence than a familiar subject line.

Operational checks for production

Before shipping the flow, I check the following:

Token values are hashed and never written to ordinary logs.
Expired and consumed leases cannot be used a second time.
A unique idempotency key prevents duplicate send side effects.
The outbox has retry limits and a visible dead-letter state.
Metrics separate API acceptance, provider handoff, delivery, and token consumption.
Test inboxes are isolated per run and cleaned up after the lease ends.

It is usefull to keep those stages separate in dashboards. A successful 202 Accepted only proves that the API accepted work; it does not prove that the email arrived or that the token was consumed. The metrics should stay seperated even when the first version of the dashboard is small.

For development, a temp mail so address can help check a flow manually, but it is not an authentication factor. Keep production verification tied to the user-controlled address and enforce the same token rules everywhere.

Q&A

Should every resend create a new token?

Usually, no. Within a short window, return the active lease or deliberately invalidate it before creating a replacement. Either policy is fine if it is explicit and observable.

How long should a lease last?

Choose a duration that matches the product journey and provider latency. Fifteen minutes is a reasonable starting point for many signup flows, but the important part is enforcing expires_at on consumption rather than trusting the client.

Can I use the same inbox across parallel tests?

Only with strong message ownership and a deterministic claim rule. Separate inboxes are simpler, cheaper to troubleshoot, and usually worth the small setup cost.

The central idea is modest: email verification is a state transition, not a message-shaped side effect. Model ownership and expiry in PostgreSQL, make retries idempotent in Node.js, and preserve delivery evidence. Correctness no longer depends on which email arrives last.

Node.js Auth Requests Need an Idempotency Ledger

kevindev — Tue, 13 Oct 2026 17:23:48 +0000

An email-verification endpoint looks simple until a client times out after the server has accepted the request. The browser retries, the mobile app retries again, and suddenly one user has three valid links in an inbox.

The request are not the email. They are a durable command to create or reuse a delivery attempt. Treating that command as state in PostgreSQL makes a Node.js REST API easier to retry, inspect, and operate. It also gives you a clean boundary between authentication state and the provider that eventually delivers a message.

Why sending verification email is a state transition

Consider POST /verification-emails. A client may send the same logical request more than once because of a timeout, a lost response, or a user tapping twice. If every HTTP request creates a fresh token, the service has made the client responsible for deduplication. That is a poor contract.

The endpoint should accept an idempotency key and record a small state machine:

accepted: the request was recorded, but no delivery has been claimed
queued: a worker can deliver the message
sent: the provider accepted the message
failed: delivery stopped after a retry policy
superseded: a newer verification request invalidated this one

The token itself can have a separate lifecycle. Keeping the request and token concepts distinct is useful: one request may produce one token, while multiple delivery attempts may be made for that token. That distinction pay off when support needs to answer whether a message was never queued, failed at the provider, or was delivered but never used.

For test environments, an isolated disposable email inbox can help validate the delivery edge without touching a real personal mailbox. The inbox is a test dependency, not the source of truth for whether a request was accepted.

Define the request ledger in PostgreSQL

The database needs one unique constraint that represents the client-visible operation. A compact table could look like this:

CREATE TABLE verification_requests (
  id uuid PRIMARY KEY,
  user_id uuid NOT NULL,
  idempotency_key text NOT NULL,
  token_id uuid NOT NULL,
  status text NOT NULL DEFAULT 'accepted',
  attempts integer NOT NULL DEFAULT 0,
  last_error text,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (user_id, idempotency_key)
);

CREATE INDEX verification_requests_queue_idx
  ON verification_requests (created_at)
  WHERE status = 'accepted';

The unique key should be scoped to the user or account. A global key can accidentally make two unrelated users share a result if a poorly generated client key is reused. Store a hash of a sensitive key when the key itself could reveal information; the important property is stable equality, not the original text.

When the same user sends the same key again, return the existing request. Do not silently create a new token. If the payload differs, return a conflict such as 409 Conflict; otherwise a client could reuse a key while changing the destination or verification purpose.

Make retries idempotent in a Node.js REST API

The handler should validate the request, begin a transaction, insert the ledger row, and commit before asking a worker to deliver anything. In pseudocode, the shape is straightforward:

const result = await db.tx(async (tx) => {
  const existing = await tx.oneOrNone(
    `SELECT id, status, token_id
       FROM verification_requests
      WHERE user_id = $1 AND idempotency_key = $2`,
    [userId, idempotencyKey]
  );

  if (existing) return existing;

  const token = await createVerificationToken(tx, userId);
  return tx.one(
    `INSERT INTO verification_requests
       (id, user_id, idempotency_key, token_id)
     VALUES ($1, $2, $3, $4)
     RETURNING id, status, token_id`,
    [requestId, userId, idempotencyKey, token.id]
  );
});

await queue.publish({ requestId: result.id });
return res.status(202).json({ requestId: result.id, status: result.status });

In production, the insert and queue publish need an outbox or another durable handoff. Otherwise the process can commit the database row and crash before publishing the job. This is where many implementations gets their "accepted" response wrong: accepted must mean the system has a recoverable path to delivery, not merely that an in-memory function returned.

An outbox row in the same transaction lets a worker claim work with FOR UPDATE SKIP LOCKED. The worker increments attempts, records provider results, and uses a bounded retry schedule. It should be safe for the same job to be claimed twice, because the provider call and the local state update can still race.

For operational consistency, the response should be boring and clear, which is a feature for maintaners. A repeat request can return 200 with the existing status, while a newly accepted request returns 202. Pick a policy and document it; clients should not have to infer whether a timeout created a second token.

Separate database success from email delivery

Do not mark a verification token as consumed when the email is sent. Sending proves only that a provider accepted a message. Consumption happens when the user presents the token and the API atomically changes it from issued to consumed.

The delivery worker should keep enough evidence to answer three questions:

Was the request accepted and committed?
Was a delivery job claimed and attempted?
Did the provider return an accepted, rejected, or unknown result?

Those facts are more useful than a single email_sent = true flag. They also make alerting possible: a growing accepted backlog points to queue health, while repeated provider rejections point to a different boundary.

Test duplicate and delayed requests

A good test suite should also check the unhappy pathes. At minimum, cover these cases:

two concurrent requests with the same user and idempotency key create one token
the same key with a changed payload returns a conflict
a committed row survives a worker restart before delivery
a second delivery attempt does not create a second verification token
a consumed token cannot be replayed after another request arrives
an expired request is visible to cleanup and support queries

Include realistic malformed input in the test fixtures, such as temp gamil com or tem email, but keep those strings out of production validation rules unless they represent an explicitly supported test case. The spelling is not the interesting part; the boundary between user input, token state, and delivery work is.

If browser tests poll for the message, use a clear stop rule and fresh evidence. This complements less guesswork in Playwright email waits: the test should know which request ID and token it is waiting for, rather than accepting the first message it sees.

A short implementation checklist

Require an idempotency key for the verification command.
Enforce uniqueness per user and key in PostgreSQL.
Return an existing result for a safe retry.
Reject a reused key whose payload differs.
Commit an outbox event with the request state.
Keep delivery attempts separate from token consumption.
Add metrics for accepted, queued, sent, failed, and superseded states.
Retain enough history to investigate delayed or duplicate requests.

The pattern is intentionally small. It does not remove every email provider failure, but it makes each failure observable and each retry predictable. That is the real goal of an idempotency ledger.

Questions engineers usually ask

Should every verification request get a new token?

No. A new logical request can get a new token, but a retry of the same idempotency key should return the original request. A separate endpoint or an explicit new key can represent "send again."

How long should the ledger be retained?

Keep terminal rows for the period needed for support, security review, and metrics. Then archive or delete them with a separate retention job. Do not let cleanup remove the evidence needed to explain a delivery incident.

Is an idempotency key enough without an outbox?

No. The key prevents duplicate logical requests, but it does not bridge a successful database commit and a failed queue publish. Use a transactional outbox or a queue with a commit-aware integration.

What if the provider result is unknown?

Record unknown and retry according to the provider's guidance. Do not claim certainty from a network timeout. A small amount of ambiguity in the ledger is safer than telling a user that a message definitely was not delivered.

PostgreSQL Token Cleanup for REST APIs

kevindev — Tue, 13 Oct 2026 14:22:53 +0000

Verification tokens are usually designed as if the only important event is a successful click. In a real REST API, the harder work happens around that click: a user requests another email, a worker retries delivery, an old browser tab submits a token, or a cleanup job removes evidence before support can inspect it.

The database should make those cases explicit. A small PostgreSQL token table, a clear state transition, and a bounded cleanup worker can keep an authentication flow predictable without turning it into a large distributed system.

Why token cleanup is part of the API contract

An email verification token is temporary state, not just a random string. It has an owner, an intended action, an issued time, an expiration time, and usually a consumption time. If those values are left implicit, different parts of the service will invent their own rules.

For example, the REST API may consider a token valid for 15 minutes while the worker retries for an hour. A cleanup query might delete rows after 10 minutes, and the Node.js handler might still return a generic success response when the token is already gone. The user sees a confusing loop, while the logs show only "invalid token".

I treat the lifecycle as a contract with four useful states:

issued: the token exists but has not been used
consumed: the intended action completed successfully
expired: the validity window ended without consumption
revoked: a newer request or a security action invalidated it

This also fits a broader threat model for OAuth signup, where proof of email ownership is only one part of the trust boundary.

Model the token lifecycle in PostgreSQL

Store a hash of the token rather than the raw value. The email link can carry the raw secret, but a database leak should not immediately turn every unexpired link into a working credential. A minimal table can look like this:

CREATE TABLE verification_tokens (
  id uuid PRIMARY KEY,
  user_id uuid NOT NULL,
  token_hash bytea NOT NULL UNIQUE,
  purpose text NOT NULL,
  status text NOT NULL DEFAULT 'issued',
  issued_at timestamptz NOT NULL DEFAULT now(),
  expires_at timestamptz NOT NULL,
  consumed_at timestamptz,
  revoked_at timestamptz,
  created_request_id text NOT NULL
);

CREATE INDEX verification_tokens_expiry_idx
  ON verification_tokens (expires_at)
  WHERE status = 'issued';

The partial index keeps the cleanup path focused on live rows. I also like created_request_id because it connects a token to an idempotency key or request trace. That makes a duplicate-send investigation much less guessy.

Do not use a cleanup delete as the validity check. The API should validate status = 'issued' and expires_at > now() in one transaction. Cleanup is maintenance; it should never be the authority for whether a link works.

Use a bounded cleanup worker

A cleanup job should do small batches instead of scanning and deleting every expired row in one transaction. Large deletes create lock pressure, make vacuum work harder, and can delay unrelated authentication requests.

WITH expired AS (
  SELECT id
  FROM verification_tokens
  WHERE status = 'issued'
    AND expires_at <= now()
  ORDER BY expires_at
  FOR UPDATE SKIP LOCKED
  LIMIT 500
)
UPDATE verification_tokens AS token
SET status = 'expired'
FROM expired
WHERE token.id = expired.id;

Marking rows as expired preserves useful history. A later retention job can remove old terminal rows after the support and audit window. The exact retention period depends on the product, but mixing "not valid anymore" with "physically absent" is a common source of observabilty gaps.

Run this statement repeatedly with a short delay, and stop when the batch is empty. Multiple workers can safely share the queue because SKIP LOCKED avoids waiting on rows another worker already claimed. Keep the transaction short; a cleanup worker is a dependancy of the system, not the system itself.

Keep retries and consumption observable

Token consumption must be atomic. The handler should update only an issued, unexpired token and return the result of that update:

UPDATE verification_tokens
SET status = 'consumed', consumed_at = now()
WHERE token_hash = $1
  AND status = 'issued'
  AND expires_at > now()
RETURNING user_id, purpose;

If no row is returned, the API can distinguish an already-used token from an expired one by doing a safe follow-up lookup, or it can deliberately expose one generic response to reduce information leakage. The important point is that two requests cannot both consume the same token.

Record counters for issued, resent, consumed, expired, and revoked tokens. Add the token purpose and a request identifier, but never log the raw token. When a test note says temp mailid, that may be harmless shorthand, but production logs still need a stable, non-secret correlation value.

For end-to-end checks, capture the message timestamp and the token request ID rather than merely selecting the newest email. The same principle appears in fresh evidence when polling an email inbox. It prevents a retry from quietly consuming an older message.

Test the expiry boundary

Time-based tests become brittle when they use the wall clock directly. Inject a clock into the Node.js service and test at exact boundaries:

A token one second before expires_at is accepted.
A token at or after expires_at is rejected.
Two concurrent consumption requests produce one success.
A resend revokes or supersedes the previous issued token.
Cleanup does not change a consumed or revoked token.

Also test a delayed worker and a retry after a database timeout. The API response should not claim a new token was sent unless the outbox or delivery contract recorded that attempt. Otherwise a temporary database error can result in an email the user never receives, occured alongside a misleading success message.

A practical checklist

Hash verification secrets at rest.
Store explicit status, issued_at, and expires_at values.
Enforce one-time consumption with a conditional update.
Keep cleanup in bounded batches with SKIP LOCKED.
Preserve terminal rows long enough for support and audit needs.
Correlate resends, messages, and API requests without logging secrets.
Inject time so expiry and retry tests are deterministic.

The pattern is deliberately modest. PostgreSQL can own token state, the REST API can own the contract, and a small worker can handle retention. That separation keeps authentication behavior understandable when the happy path is no longer the only path.

REST API Verification State Machines in PostgreSQL

kevindev — Mon, 12 Oct 2026 08:22:44 +0000

Email verification looks like a small feature, but its reliability depends on clear state transitions, database constraints, and idempotent API behavior.

Why verification needs an explicit state machine

Many implementations start with one verified boolean and a token column. That is enough for a demo, but it becomes hard to reason about when a user requests a second email, clicks an old link, or retries after a network timeout.

I prefer modelling the verification flow as a small state machine:

pending: a verification request exists and has not been completed.
sent: a message was scheduled for delivery.
verified: the token was consumed successfully.
expired: the token can no longer be used.
revoked: a newer request invalidated this one.

The state is not only documentation. It gives the REST API something concrete to enforce. An expired token cannot move back to pending, and a verified token cannot be consumed twice. This sounds obvious, but vague states are where auth bugs usually begin.

The PostgreSQL model

A separate row for each verification attempt is more useful than overwriting a single token. It preserves an audit trail and lets the application reject an older request without guessing which email was most recent.

CREATE TABLE email_verifications (
    id              uuid PRIMARY KEY,
    user_id         uuid NOT NULL,
    token_digest     bytea NOT NULL UNIQUE,
    state            text NOT NULL CHECK (state IN (
        'pending', 'sent', 'verified', 'expired', 'revoked'
    )),
    expires_at       timestamptz NOT NULL,
    consumed_at      timestamptz,
    created_at       timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX email_verifications_user_pending_idx
    ON email_verifications (user_id, created_at DESC)
    WHERE state IN ('pending', 'sent');

Store a digest of the token, not the raw token. The link can contain a random value, while the database only receives its hash for lookup. When a user requests a new link, revoke previous pending and sent rows in the same transaction, then insert the new row.

The partial index keeps the common query small. It also makes the intended active states visible to the next engineer. A little explicitness here saves a lot of debugging later, specially when traffic grows.

For the email side, an outbox row can represent the delivery request. The queryable PostgreSQL outbox checks pattern is useful when the API must commit user state and delivery intent together.

Make the REST API transitions idempotent

The verification endpoint should be safe to retry. A client may receive a timeout after the server commits, so returning an error for the second request can make a successful flow look broken.

For example, the endpoint can follow this sequence:

Hash the presented token.
Start a transaction and select the matching row with a lock.
Reject it if it is missing, expired, or revoked.
If it is already verified, return the same success shape as a first successful request.
Otherwise update it to verified, set consumed_at, and mark the user as verified.
Commit before sending the response.

The important part is the conditional update. In a busy system, two requests can present the same token at almost the same time. A lock or a guarded UPDATE ... WHERE state IN ('pending', 'sent') ensures only one request performs the transition.

The response should not reveal whether a token was valid for a particular account. Use a stable public result such as verified, already_verified, or a generic failure, depending on the threat model. Error details in logs can be richer than details returned to an unknown caller.

If test data uses a frozen plan for repeatable automation, add the verification state and token identifier to the run manifest. That makes a flaky test easier to replay. A dummy e mail address is fine for a fixture, but it should never be treated as proof that delivery happened.

Keep email delivery outside the verification transaction

Sending an email while holding a database transaction creates an awkward failure window. The provider can be slow, the request can time out, and the database lock can remain open longer than expected.

Use a transactional outbox instead:

The API transaction creates the verification row and an outbox event.
A worker claims the event with a short lease.
The worker sends the message and records success or a retryable failure.
A cleanup job expires old verification rows and abandoned events.

This also separates authentication correctness from provider availability. A provider outage should delay a message, not make the user record half-updated. The worker needs bounded retries, because retrying a permanently rejected address forever is just noise and cost.

Be careful with expiration. Checking expires_at in application code is necessary, but the database transition should check it too. Otherwise a request that waited in a queue can consume a token after the application made its first decision. The two checks are slightly repetitive, and thats intentional.

Operational checklist

Before shipping the endpoint, I check the following:

Every legal state transition has a test.
Two concurrent requests cannot consume one token twice.
A newer request revokes older active requests.
Token values are never logged in raw form.
Expiration is checked during the write, not only during the read.
Outbox retries have a maximum or a dead-letter path.
Metrics separate invalid, expired, already-used, and successful attempts.
Cleanup queries use indexes and are safe to run more than once.

The wording in a few errors may look small, but it affects support and incident response. Keep the public API stable even if internal reasons are refined later. In practise, a predictable contract is more valuable than a clever one.

Final thoughts

An email verification flow is an authentication workflow with a delivery dependency. Treating it as a state machine makes the rules visible; PostgreSQL transactions make the transitions enforceable; and an outbox keeps delivery from controlling account correctness.

The same design works whether the message goes to a corporate inbox, a temp mail so address used for a controlled test, or another mailbox provider. The important boundary is that the system records what it knows: a token was created, a delivery was requested, and a token was consumed. Those are different facts, and keeping them seperate makes the API easier to operate.

REST API Verification Links Need a Token Ledger

kevindev — Sun, 11 Oct 2026 02:23:31 +0000

Email verification often starts as a small endpoint: create a token, send a link, and mark the account as verified when the link is opened. The hard part appears later, when users click twice, mail clients prefetch links, workers retry delivery, or two requests arrive at the same time.

A verification link is not just a random string. It is a state transition in an authentication workflow. Treating it as a short-lived ledger entry makes the REST API easier to reason about, and PostgreSQL can enforce several of the rules that application code tends to miss.

The verification link is a state transition

The useful states are small and explicit:

issued -> consumed
issued -> expired
issued -> revoked

Only an issued token should be accepted. A consumed token must not become valid again just because the same URL was loaded in a second browser tab. An expired token should produce a response that tells the client to request a new one, not a generic server error.

The distinction matters for retries. A mobile client may retry a request after a network timeout even though the first request committed successfully. If the endpoint does not define its behavior for that case, authentication bugs will look random. They arent random; the state model is incomplete.

Store token state, not only a hash

Never store a raw verification token when a digest is enough. Return the opaque value only in the email link, then store a hash and the metadata needed to validate it:

CREATE TABLE email_verification_tokens (
  id           uuid PRIMARY KEY,
  user_id      uuid NOT NULL REFERENCES users(id),
  token_hash   bytea NOT NULL UNIQUE,
  issued_at    timestamptz NOT NULL,
  expires_at   timestamptz NOT NULL,
  consumed_at  timestamptz,
  revoked_at   timestamptz
);

The expires_at value is part of the record, rather than an assumption in the handler. This makes expiration visible during incident review. Keep the token lifetime short enough for the product risk, and make sure clocks are managed consistently across API and worker hosts.

The hash also reduces the impact of a database snapshot leak. It does not solve every account-security problem, but it prevents a copied token column from becoming an immediate set of usable links. A temp mailid used in a test should be treated as disposable data too, and should never be mixed with production identities.

Make the REST API replay-safe

The consuming endpoint can be POST /v1/email-verifications/consume. It should hash the presented value, select the matching row, and consume it inside one transaction. The critical operation is conditional:

UPDATE email_verification_tokens
SET consumed_at = now()
WHERE token_hash = $1
  AND consumed_at IS NULL
  AND revoked_at IS NULL
  AND expires_at > now()
RETURNING user_id;

If one row returns, the request can mark the user verified. If no row returns, the token is invalid, already consumed, revoked, or expired. The API may expose a safe, stable error category, but it should not reveal whether a token once belonged to a real account.

For concurrent requests, the database update is the boundary that decides the winner. Do not perform a read followed by an unconditional write; both requests can observe the same issued state. The endpoint should be boring about retries. Boring is good here.

For a wider operational view, auditable background-job runs show the same principle: a durable receipt is more useful than a log line when work is retried. Record a token ID, user ID, outcome, and request correlation ID, while keeping the secret itself out of logs.

Use PostgreSQL to enforce the contract

Application validation is necessary, but constraints provide the last line of defense. Add indexes for the lookup and for cleanup:

CREATE INDEX email_verification_tokens_expiry_idx
  ON email_verification_tokens (expires_at)
  WHERE consumed_at IS NULL AND revoked_at IS NULL;

If the product permits only one active token per user, enforce that rule with a partial unique index. If it permits several, attach a generation number or issuance reason so a newer request can revoke older tokens deliberately. The answer should be a product decision, not an accidental side effect of whichever worker ran first.

Cleanup can delete old rows asynchronously. It doesnt need to run in the request path. Keep consumed records for a bounded audit period, then remove them with a scheduled job. A short retention policy makes storage predictable and limits the amount of authentication history exposed by a future incident.

Testing with isolated inboxes

End-to-end tests should verify the API contract, not depend on a shared mailbox. An isolated inbox or a disposable email generator can provide a recipient for a short-lived test account, while the test records the message ID and token consumption result. Do not put the service link in a reusable fixture; each run needs a fresh token.

Include cases for an expired token, a second click, two concurrent consumes, a revoked token, and a delivery retry. A useful email-test failure taxonomy helps keep delivery failures separate from API-state failures. The label temp org mail may appear in old test data, but the system should normalize fixture names and avoid letting labels affect security decisions.

Common questions

Should a second click return success?

Usually no. Return a stable already_consumed category so the client can show a useful recovery path. Making every old link look successful hides replay attempts and makes debugging harder.

Should token consumption and user verification share a transaction?

Yes, when the user update depends on that token. Commit both changes together, or the system can consume a link while leaving the account unverified after a partial failure.

Do I need a queue for verification emails?

Not for the token state itself. A queue is useful for delivery, but issuance and consumption still need transactional boundaries in the API and database.

Implementation checklist

Generate high-entropy opaque values and store only their hashes.
Give every token an explicit expiry, consumed state, and revocation state.
Consume with one conditional database update inside a transaction.
Make concurrent requests deterministic and keep secrets out of logs.
Test retries, expiry, replay, revocation, and delivery separately.
Retain audit data for a defined period, then clean it up.

The main design payoff is clarity. The email is only the transport; PostgreSQL-backed state is what makes the verification decision safe, repeatable, and explainable.

Node.js Email Verification Needs Atomic Tokens

kevindev — Sat, 10 Oct 2026 02:22:57 +0000

Email verification looks like a small feature: create a token, send a message, and accept the token when the user clicks it. In a real Node.js service, the difficult part is not generating the token. It is deciding what happens when the user clicks twice, the link expires during a retry, or two API workers process the same request at nearly the same time.

The reliable design is to treat verification as a state transition backed by one atomic database operation. The email is only the delivery channel. PostgreSQL remains the authority for whether a token is valid and whether it has already been consumed.

The race behind a familiar verification bug

A naive endpoint usually does this:

Read the verification row.
Check that used_at is empty and expires_at is in the future.
Mark the row as used.
Activate the user.

Each step seems fine in isolation. The problem is that two requests can both finish step 2 before either request reaches step 3. A double-click, a browser retry, or two load-balanced workers can then accept the same token twice. The result may be duplicate welcome actions, repeated audit events, or an account activated by a request that should have failed.

Email delivery creates a similar ambiguity. A disposable temporary email inbox or a create temp mail workflow may expose delayed messages, duplicates, or an old verification link. Test coverage should therefore assert both token behavior and message selection. Parallel email test isolation is useful context when several workers exercise the same signup flow.

Store a digest, not the raw token

The URL can contain a random, single-use value, but the database does not need to store that value directly. Store a cryptographic digest instead. If a database snapshot is exposed, the attacker should not immediately have usable verification links.

import { createHash, randomBytes } from "node:crypto";

export function issueToken(): { raw: string; digest: string } {
  const raw = randomBytes(32).toString("base64url");
  const digest = createHash("sha256").update(raw).digest("hex");
  return { raw, digest };
}

Store the digest, user ID, expiry time, and consumption time in a dedicated table. Keep the raw value only long enough to construct the link and hand it to the mail provider. Do not log it, even at debug level. That logging habit is easy to miss and painful to remove later.

CREATE TABLE email_verification_tokens (
  token_digest text PRIMARY KEY,
  user_id bigint NOT NULL REFERENCES users(id),
  expires_at timestamptz NOT NULL,
  used_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX email_verification_tokens_active_idx
  ON email_verification_tokens (token_digest, expires_at)
  WHERE used_at IS NULL;

The partial index is not a security boundary, but it keeps the common lookup focused on tokens that could still be consumed. A cleanup job can remove old rows later; cleanup should never decide whether a current request is valid.

Consume the token in one PostgreSQL statement

The key operation is a conditional UPDATE. It checks the digest, expiry, and unused state while taking the row lock. Only a request that updates one row has won the token.

UPDATE email_verification_tokens
SET used_at = now()
WHERE token_digest = $1
  AND used_at IS NULL
  AND expires_at > now()
RETURNING user_id;

In Node.js, treat an empty result as a normal rejected verification, not as a database error. The query can return zero rows because the token is unknown, expired, or already consumed. Those causes can be logged internally with a safe reason, while the public response stays deliberately broad.

After the token is consumed, activate the user in the same transaction. If activation fails, roll back the token update too; otherwise the user could receive a “try again” response while their only token is already gone.

await client.query("BEGIN");
try {
  const result = await client.query<{ user_id: number }>(consumeSql, [digest]);
  if (result.rowCount !== 1) {
    await client.query("ROLLBACK");
    return { kind: "rejected" as const };
  }

  await client.query(
    "UPDATE users SET email_verified_at = now() WHERE id = $1",
    [result.rows[0].user_id],
  );
  await client.query("COMMIT");
  return { kind: "verified" as const };
} catch (error) {
  await client.query("ROLLBACK");
  throw error;
}

The transaction must use the same connection for every statement. Returning a client to the pool between BEGIN and COMMIT breaks the boundary, a mistake that can be suprisingly hard to spot in local tests.

Make the REST API state machine explicit

The endpoint should expose a small, documented contract:

200 OK when this request verifies the account.
400 Bad Request when the token format is invalid.
410 Gone when a well-formed token is expired or already consumed, if that distinction is useful to the client.
500 Internal Server Error only for an actual service failure.

Do not let the client infer success from a redirect alone. Return a stable response body and an internal request ID for support diagnostics. If the product wants repeated clicks to be harmless, it can render the same confirmation page after a 410; that is a UX choice, not a reason to accept the token a second time.

When testing the mail side, assert recipient, run marker, subject, and link before consuming the token. Matching the intended verification message matters because an old message can contain a perfectly valid-looking URL for a different test run.

Test expiry and concurrent clicks

The high-value tests are small and deterministic:

A fresh token updates exactly one user and cannot be used again.
An expired token updates zero rows.
Two concurrent requests produce one success and one rejection.
A failure during user activation rolls back token consumption.
A malformed token never reaches a database lookup.
A repeated mail message cannot make a test choose the wrong verification link.

Use a transaction-capable PostgreSQL test instance for the concurrency case. A mock that returns a row twice will not prove that row locking and the conditional update work together. Also test the boundary where expires_at equals the current database time; application and database clocks should not quietly disagree.

Some support searches contain labels like temp org mail or tepm mail com. Keep those terms out of token logic and analytics dimensions; they are just misspelled descriptions, not a security category. This little distinction saves confusion in incident reports.

Operational checklist

Hash random tokens before persistence.
Never log raw verification URLs or token values.
Consume and activate inside one PostgreSQL transaction.
Use one pooled connection for the transaction.
Give tokens a clear expiry and cleanup policy.
Make the one-time behavior visible in API documentation.
Record safe rejection reasons and a request ID.
Test two workers clicking the same link at once.
Assert that email tests select the message for their own run.

The main design decision is simple: delivery can be delayed or duplicated, but token consumption must be atomic. Once that boundary is explicit, the Node.js handler, REST API responses, PostgreSQL schema, and test fixtures all become easier to reason about.

Questions that come up in review

Should the token be deleted instead of marked used?

Usually, keeping used_at is more useful. It supports audit queries and makes a second click distinguishable from an unknown token. A retention job can delete old rows after the audit window.

Should verification be idempotent?

The user-facing confirmation page can be repeatable, but token consumption should stay one-time. Keep those concepts separate: a repeated request may render a friendly result without changing the account again.

Is a short token lifetime enough?

No. Expiry limits the window, while hashing, TLS, redaction, atomic consumption, and rate limiting address different risks. They work together, they dont replace one another.

Designing a Verification Inbox Contract for Node.js APIs

kevindev — Fri, 09 Oct 2026 11:22:54 +0000

Email verification is often treated as a side effect of account creation: send a message, wait for a link, and mark the user as verified. In a real REST API, that side effect has its own delivery delay, retries, database state, and test inbox. The design gets much easier when the email is treated as a contract with an explicit receipt.

The inbox is part of the API contract

An authentication endpoint usually has at least two independent outcomes:

The user record is created or updated.
A verification message is accepted for delivery.

Those outcomes should be connected by a correlation ID, not by the assumption that the newest message in a mailbox belongs to the newest request. A request can be retried by a client, a worker can retry a provider call, and a test runner can poll while an older message is still visible.

The API response can expose a non-sensitive verification_id while keeping the actual token out of logs:

{
  "user_id": "8f3a4c1e",
  "verification_id": "ver_01JY7K8Q",
  "status": "pending"
}

The receipt become useful when every later action can refer to it. A test using a free temporary email address can wait for the matching recipient and correlation ID instead of guessing from message order. Search noise such as temp org mail or tempail should not become part of that domain model.

Model verification as a receipt

Keep a verification record separate from the user row. It should describe what was issued, when it expires, and whether it was consumed. The important fields is small and deliberately boring:

verification_id
user_id
token_hash
correlation_id
expires_at
consumed_at
created_at

Store a hash of the token, not the raw token. The raw value belongs only in the link sent to the user. A correlation_id can be copied into provider metadata or a test-only header, but it should not contain an email address or secret.

The endpoint that consumes a token should be safe to call more than once. If the token was already consumed, return a stable result such as already_verified rather than changing the user back to an unverified state. The original request may have succeeded even when the client never received its response, so retries are normal behavior.

PostgreSQL constraints that make retries boring

The database should enforce the rules that application code is likely to forget under concurrency. A simplified schema might look like this:

CREATE TABLE email_verifications (
    id              uuid PRIMARY KEY,
    user_id         uuid NOT NULL REFERENCES users(id),
    token_hash      bytea NOT NULL,
    correlation_id  text NOT NULL,
    expires_at      timestamptz NOT NULL,
    consumed_at     timestamptz,
    created_at      timestamptz NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX one_active_verification_per_user
    ON email_verifications (user_id)
    WHERE consumed_at IS NULL;

Whether one active token per user is the right policy depends on the product. The useful part is deciding the policy explicitly. A retry can arrive after the original request was successful, so the row must not gets a second meaning.

When issuing a token, use a transaction to retire or replace the previous active record and insert the new one. When consuming it, update only a row that is unconsumed and unexpired:

UPDATE email_verifications
SET consumed_at = now()
WHERE id = $1
  AND consumed_at IS NULL
  AND expires_at > now()
RETURNING user_id;

If no row is returned, the token is expired, unknown, or already used. Do not returns a detailed reason to an unauthenticated caller; that can make account enumeration easier.

Read the message with a cursor

The mailbox client needs a message cursor or a provider message ID. “Read the latest email” is not a reliable assertion when multiple jobs share infrastructure. Filter by recipient, subject, correlation ID, and a bounded time window. Then record which message was consumed.

For browser-driven tests, the same principle applies to waiting. Use bounded email waits with a deadline and a useful failure receipt, rather than adding another fixed sleep. A test that only checks a 200 response miss the most important part of the flow: whether the right message was delivered and consumed.

Keep the test inbox scoped to the run when possible. Isolated inbox checks are especially valuable when retries and parallel jobs are involved. The inbox is test data, not a shared dumping ground.

Expiry and cleanup are part of correctness

Expiration belongs in both the token query and the cleanup process. The API must reject an expired token immediately. A scheduled worker can later delete old verification rows and remove test messages after their retention window. The cleanup worker run independently, because a request finishing successfully does not prove that every temporary resource was removed.

Keep operational records small: verification ID, user ID, state, provider message ID, and timestamps. Do not log the token, full message body, or private links. This makes incident review safer and makes it possible to answer whether the message was sent, received, and consumed.

A practical verification checklist

Generate a cryptographically random token and store only its hash.
Attach a correlation ID to the verification record and delivery request.
Make issuance and consumption idempotent.
Enforce expiry in PostgreSQL, not only in application code.
Poll a run-scoped inbox by cursor, recipient, and correlation ID.
Set a clear timeout and return a failure receipt from tests.
Delete or redact message data after the retention period.
Measure delivery latency separately from API response latency.

The last distinction matters. A fast endpoint can still hide a slow worker or an unavailable mail provider. It also make capacity problems visible before users report missing verification links.

Questions worth answering before shipping

What happens when the user requests a second link? Decide whether the first token is revoked, whether both remain valid, and how the message test identifies the newest valid receipt.

Can a replay change account state? It should not. Consumption needs an atomic condition and a stable response for already-used tokens.

Who owns failed cleanup? Name the worker, metric, and alert. A temporary inbox with no owner is just hidden state waiting to become a flaky test.

An email verification flow is more reliable when its message, token, and cleanup behavior are explicit parts of the backend design. The result is not only better tests; it is an authentication path that stays understandable when networks, clients, and workers retry at the same time.

REST API Verification Needs an Email Lease

kevindev — Fri, 09 Oct 2026 02:24:27 +0000

Email verification looks like a simple two-request flow: create an account, send a message, then accept a token. In a production REST API, it is closer to a distributed workflow. The send can be retried, delivered twice, or consumed twice.

The failure mode I see most often is not a bad token. It is an ownership problem. Two requests believe they are allowed to consume the same verification message, or a delayed message arrives after the user has already requested a replacement. A lease gives the backend a clear answer to a useful question: which attempt currently owns this verification step?

Why verification retries need ownership

Suppose a mobile client calls POST /verification/email and times out. The server may have committed the request even though the client never saw the response. The client retries, and the API creates a second message. Later, both links are valid, or the older link unexpectedly wins.

The same issue appears in automated environments that use a temp mailbox or a free temporary email address for test accounts. A mailbox can contain several plausible messages, but plausibility is not identity. The test needs to know which request created which message and which attempt is allowed to claim it.

An email lease is a short-lived ownership record tied to a user, a verification purpose, and an idempotency key. It should have an owner, an expiry time, and a state. The state makes the workflow visible instead of hiding it inside a polling loop.

Model the email as a leased resource

I use four states for a verification delivery:

requested -> leased -> consumed
                 \-> expired

requested means the API accepted the intent but has not assigned a delivery attempt. leased means one worker owns the attempt for a bounded period. consumed means the token was accepted successfully. expired means another attempt may replace it, subject to the product's rate limits.

The lease should not be the token itself. Keep the token hash separate, and store only enough metadata to correlate the delivery:

create table verification_deliveries (
  id bigserial primary key,
  user_id bigint not null,
  purpose text not null,
  idempotency_key text not null,
  token_hash text not null,
  state text not null default 'requested',
  lease_owner text,
  lease_until timestamptz,
  consumed_at timestamptz,
  created_at timestamptz not null default now(),
  unique (user_id, purpose, idempotency_key)
);

The unique constraint is important. It lets a retry find the original delivery instead of creating another one. The lease_owner can be a worker ID or request trace ID; it should be safe to log, unlike the raw verification token.

Implement the lease with PostgreSQL

Claiming a delivery must be atomic. A worker can select an unleased row, verify that its lease is available, and update it in one transaction. FOR UPDATE SKIP LOCKED is useful when several delivery workers share a queue:

begin;

select id
from verification_deliveries
where state = 'requested'
   or (state = 'leased' and lease_until < now())
order by created_at
for update skip locked
limit 1;

update verification_deliveries
set state = 'leased',
    lease_owner = $1,
    lease_until = now() + interval '2 minutes'
where id = $2;

commit;

The worker should renew only while it is making progress. A lease that never expires becomes a stuck job. A lease that is too short causes duplicate delivery when a slow provider is still processing the first attempt. The right duration depends on provider latency, but the decision should be explicit and observable.

The send operation also needs a receipt. Record the provider message ID, response status, and attempt timestamp after the provider accepts the message. If the provider call times out, the result is unknown; dont immediately release the lease and send again. Mark the attempt as uncertain, then reconcile it with a provider lookup or a controlled retry policy.

Keep the REST API retry-safe

The API endpoint should accept an idempotency key from the client or generate one at the boundary. Repeating the same key should return the existing delivery status, not create a new token. A different key can represent a deliberate new request, subject to a cooldown.

For token consumption, use a conditional update:

update verification_deliveries
set state = 'consumed', consumed_at = now()
where id = $1
  and state = 'leased'
  and lease_until > now()
  and token_hash = $2
returning id;

If no row is returned, the API should return a stable error such as verification_expired or verification_already_used. Do not leak whether a token hash was close to matching. Authentication responses are easier to operate when their error vocabulary is small and predictable.

Keep token consumption and the account activation update in the same transaction when possible. That way, a successful response means both facts were committed. If they must be separate, use an explicit state transition and a repair job; a vague 200 OK thats emitted before activation is durable will create support cases.

Testing expiry and cleanup

Test the boundary cases as first-class scenarios:

Two workers try to claim the same delivery. Exactly one gets the lease.
A worker pauses past lease_until. A replacement can claim the row.
The same idempotency key is submitted repeatedly. The delivery count stays one.
The provider times out after accepting the message. Reconciliation does not create an uncontrolled duplicate.
A consumed token is submitted again. The response is stable and no account state changes.

For browser tests, keep the correlation ID and provider message ID in the test receipt. Proving temporary inbox deletion is part of cleanup, but deletion should happen after the receipt is stored. A test value like tempail or dummy e mail can cover input validation; it should never be accepted as a real delivery address.

It is also worth testing the cleanup worker. Expired leases need a clear owner, and old token hashes should have a retention policy. The cleanup job doesnt need to delete every row immediately; it does need metrics for expired, reconciled, and permanently failed deliveries. The receipt is durable evidence; logs alone isnt enough.

Final takeaways

Email verification becomes more predictable when delivery attempts have ownership, expiry, and an idempotent identity. PostgreSQL can enforce the important parts: one request key maps to one delivery, one transaction claims a lease, and one conditional update consumes a token.

The lease is not a replacement for provider reliability or client-side retries. It is the boundary that makes those behaviors safe to reason about. When a request fails, the system can say whether it was still leased, expired, delivered, consumed, or awaiting reconciliation. Thats much more useful than simply sending another email.

REST APIs Need a Verification Token Inbox

kevindev — Thu, 08 Oct 2026 08:23:30 +0000

Email verification is usually described as a send operation: create a token, send an email, and return success. In a real backend, that description hides the hardest part. The application must know which token is current, whether it has been consumed, and what to do when a client retries while the mail provider is slow.

I prefer treating verification as an inbox with a small, explicit state machine. The REST API writes an intent to PostgreSQL, a worker delivers the message, and a confirmation endpoint consumes the token exactly once. This separates authentication state from provider behaviour and makes failures easier to explain.

The same boundary is useful in staging. A burner email can help a developer inspect a real confirmation message, but test systems still need an isolated record and a cleanup policy. A string such as temp org mail may appear in old fixtures, so it is worth keeping fixture naming seperate from production identity data.

Why verification tokens need an inbox

An email provider call has an uncertain result. The connection can fail before the response arrives, or a worker can crash just after sending. If the API only stores a token in memory, a retry may create a second valid token and leave the user unsure which message to trust.

An inbox record gives each request a durable identity. It can contain:

verification_id
user_id
token_digest
status: pending | sent | consumed | expired
attempt_count
expires_at
created_at

Store a digest instead of the raw token. The raw value belongs in the email link; the database only needs to compare a hash supplied by the confirmation request. This limits the impact of a database read leak, and it keeps the token lifecycle visible to operators.

Model the token lifecycle explicitly

There are three decisions that should not be mixed together:

Issuing creates a new verification attempt.
Delivering moves an attempt through the mail provider workflow.
Consuming accepts a token once and changes the account state.

For an account that requests another message, mark older pending tokens as superseded before inserting the new one. The client can safely ask for a resend, while the server makes only the newest token valid. This is less suprising than accepting several links and hoping the user clicks the intended one.

I also put a short expiration on the token and a longer retention period on the audit row. The token should stop working quickly; the operational record can remain long enough to answer support questions without retaining the secret itself.

Claim tokens safely in PostgreSQL

A worker can claim pending deliveries with a transaction and row locking. FOR UPDATE SKIP LOCKED lets multiple workers scan the same queue without waiting on rows already owned by another worker.

WITH next_delivery AS (
  SELECT id
  FROM verification_deliveries
  WHERE status = 'pending'
    AND available_at <= now()
  ORDER BY created_at
  FOR UPDATE SKIP LOCKED
  LIMIT 1
)
UPDATE verification_deliveries AS d
SET status = 'sending',
    lease_until = now() + interval '60 seconds',
    attempt_count = attempt_count + 1
FROM next_delivery
WHERE d.id = next_delivery.id
RETURNING d.*;

The lease is important because a process may die while sending. A reaper can return rows with an expired lease to pending, with a retry limit and backoff. Do not hold the database transaction open while calling the provider; claim the row, commit, send, then record the result.

For deeper audit concerns, I keep the write path consistent with the PostgreSQL audits for email change APIs. The key idea is that delivery history is append-friendly evidence, not a mutable guess about the current account state.

Make the REST API idempotent

The issue endpoint should accept an idempotency key supplied by the client. Repeating the same request returns the existing verification attempt instead of creating another one. The database needs a unique constraint scoped to the account and key, plus a clear policy for an expired key.

The confirmation endpoint has a different contract:

POST /v1/email-verifications/confirm
Idempotency-Key: confirm-8f2...
Content-Type: application/json

{"token":"..."}

In one transaction, find the unexpired digest, lock it, verify the hash, mark it consumed, and update the account. A second request with the same token should return a stable result such as already_confirmed, not perform the state change twice. The response can be boring; boring is good for clients and support tooling.

When the provider response is ambiguous, the worker should retry according to a bounded policy. The authentication API should not pretend that a message was delivered merely because a job was claimed. That distinction prevents a green API response from hiding a dead inbox.

Test the failure paths

Unit tests cover token hashing and expiration, but the valuable checks are integration tests around transaction boundaries. Force a worker crash after claiming a row, then verify that the lease expires and another worker can retry it. Run two confirmation requests concurrently and assert that only one transaction consumes the token.

It is also useful to preserve a small receipt for each CI run. The approach described in these useful CI receipts for API tests makes it easier to tell a provider timeout from a database race. In my experience, this is where flaky email tests become diagnosable instead of just re-run until green.

A small production checklist

Hash tokens at rest and never log the raw value.
Enforce one current token per account, or document why not.
Add expiration, attempt limits, and delivery leases.
Use idempotency keys for issue and confirmation requests.
Make token consumption a single transactional state change.
Track provider ambiguity separately from API acceptance.
Test concurrent confirmation and worker recovery.

An email verification flow becomes much easier to maintain when the inbox is treated as a backend component, not as a side effect of an HTTP request. PostgreSQL gives the system durable state, the REST API gives clients a predictable contract, and the worker can retry without inventing a new identity each time. There are still edge cases, but they are named edge cases now—and that is a good place to start.

Email Verification Workers Need a Delivery Lease

kevindev — Thu, 08 Oct 2026 05:22:42 +0000

Email verification is often implemented as a single request: create a token, send a message, and return success. That model breaks when the mail provider times out after accepting the request, a worker crashes halfway through delivery, or two workers pick the same job.

The useful boundary is a delivery lease. The API records the verification intent in PostgreSQL, and a worker temporarily claims the resulting outbox row. A crash then leaves work available for another worker, while the lease prevents two active workers from sending the same message at the same time.

This is the pattern I reach for when an authentication flow must be boring under failure. It also keeps test data separate from real customer data; a disposable email address or free temporary email inbox can be useful for a controlled staging check, but neither replaces a server-side delivery contract.

Why a verification worker needs a lease

A queue acknowledgement is not the same as email delivery. Imagine a worker calls the provider and the network connection drops before the provider's response reaches your service. The worker cannot know whether the message was accepted. Retrying may send a duplicate, while refusing to retry may lose the verification email.

There is no universal way to remove that ambiguity across an arbitrary email provider. The practical goal is to make the duplicate safe and the state observable. Store one logical delivery per verification request, assign it a bounded retry budget, and record provider message IDs when they are available.

The lease handles a different problem: concurrent ownership. It should have an owner, an expiry timestamp, and a version or attempt number. A worker may process a row only while its lease is current. If the process dies, the expiry makes the row claimable again.

Define the outbox and lease states

Keep the state machine small. A typical row in an email_outbox table contains:

id and verification_id, with a unique constraint on the logical verification delivery
status, such as pending, sending, sent, or failed
lease_owner and lease_until
attempts, next_attempt_at, and last_error
provider_message_id and timestamps for creation and completion

The verification record should own the token and its expiration. The outbox row owns delivery attempts. Mixing those concerns makes it easy for a mail retry to accidentally create a new token, or for a token refresh to reset a delivery counter.

I also keep the token value out of ordinary logs. Log a verification ID and a short correlation ID instead. A temp mailid appearing in a debug line is not harmless if the log retention and access policy were never designed for it.

Claim work safely in PostgreSQL

Workers can claim a batch with a short transaction. FOR UPDATE SKIP LOCKED is a good fit when several workers poll the same table:

WITH candidate AS (
  SELECT id
  FROM email_outbox
  WHERE status = 'pending'
    AND next_attempt_at <= now()
    AND (lease_until IS NULL OR lease_until < now())
  ORDER BY next_attempt_at, id
  FOR UPDATE SKIP LOCKED
  LIMIT 25
)
UPDATE email_outbox AS e
SET status = 'sending',
    lease_owner = $1,
    lease_until = now() + interval '2 minutes',
    attempts = attempts + 1
FROM candidate
WHERE e.id = candidate.id
RETURNING e.*;

The transaction should commit before the worker performs the network call. Holding row locks while waiting on a provider creates unnecessary contention. The two-minute value is only an example; choose it from measured provider latency and worker shutdown behavior, then renew it for genuinely long sends.

When updating the result, include both id and lease_owner in the WHERE clause. A stale worker must not mark a row as sent after another worker has reclaimed it. This small condition prevents a late response from corrupting the current state.

Make retries and expiration explicit

Use exponential backoff with a ceiling, for example one minute, five minutes, and fifteen minutes, instead of retrying in a tight loop. Classify provider responses into transient failures, permanent failures, and unknown outcomes. Unknown outcomes deserve a retry policy plus an alert when the same logical delivery keeps oscillating.

The token expiration and delivery retry deadline should be related but not identical. A token can expire while its final message is still being attempted. In that case, stop sending it and let the API issue a fresh verification request. Otherwise users receive links that were already unusable when the message arrived.

At the API layer, accept an idempotency key for the create-verification operation. Repeating the same request should return the existing verification result, not create another outbox row. A different email payload with an existing key should be rejected as a conflict. This gives clients a stable REST API even when their timeout handling is imperfect.

For end-to-end coverage, combine database assertions with a mailbox check. A browser-level email check can validate the user-visible link, while a privacy review for email fixtures helps keep test addresses and message content inside the right boundary.

Operational checklist

Before shipping this worker, I verify the following:

The logical verification delivery has a unique database constraint.
Claims use short transactions and skip rows already leased.
Result updates reject expired or foreign leases.
Retry counts, lease age, provider latency, and permanent failures are measurable.
Expired tokens cannot be sent, even if an old job is retried.
Shutdown extends or releases leases in a predictable way.
Staging uses isolated mailboxes and redacted logs.

The important design choice is not the queue product. It is separating verification state from delivery state, then giving every worker attempt a bounded ownership period. Once that contract is in the database, provider timeouts and process crashes become recoverable cases instead of mysterious authentication bugs.

Idempotent Email Verification APIs Need Expiring Keys

kevindev — Thu, 08 Oct 2026 02:23:11 +0000

Email verification looks small until a mobile client retries a request, a worker delivers the same message twice, or a user clicks an old link. The important question is not only whether the token is valid. It is whether the whole operation is safe to repeat.

In backend work, I treat verification as a state transition with an explicit database contract. A request should be replayable without creating several active tokens, sending an unbounded number of messages, or turning an already completed verification back into a pending state. The design is less flashy than adding another queue, but it prevents a lot of operational noise.

Why verification retries need a database contract

Consider a client calling POST /v1/email-verifications. The request can time out after the server commits, so the client retries even though the original operation succeeded. If the endpoint generates a fresh token for every call, the last email may invalidate the previous links. If the endpoint has no limit, a button double-click can become a mail sending incident.

An idempotency key gives the request a stable identity. The server stores that key with the user, the requested email, the resulting verification record, and an expiry time. A retry with the same key can return the original result. A different payload with the same key must be rejected, because silently changing the meaning of a key makes debugging much harder.

This is the same kind of boundary I use when designing other API fixtures: the request, its side effects, and its response need one durable receipt. A Playwright email assertion can verify the user-visible result, but it cannot replace the server-side uniqueness rule.

Model the verification request as an idempotent command

Keep the API model small: an email address and a client-supplied idempotency key. Return a request ID and generic status without revealing whether an account exists.

POST /v1/email-verifications
Idempotency-Key: 01JZ7KQ7Q8M6N4Y2X0P3R8T5VA
Content-Type: application/json

{"email":"person@example.com"}

The handler should follow a predictable order:

Normalize the email for the product's documented policy.
Validate the idempotency key format and length.
Look up an existing key for the same user and endpoint.
Return the saved response if the payload fingerprint matches.
Otherwise, create the verification request and its token in one transaction.
Commit before handing work to email delivery.

The fingerprint matters. Comparing only the key means a buggy client could reuse it for another address and receive a misleading success response. It doesnt need the raw email; a keyed digest or scoped hash is enough for comparison.

Use PostgreSQL constraints and expiring keys

Application checks are useful, but PostgreSQL should enforce the invariant during concurrent requests. A simplified schema might look like this:

CREATE TABLE verification_requests (
  id uuid PRIMARY KEY,
  user_id uuid NOT NULL,
  email_digest bytea NOT NULL,
  token_digest bytea NOT NULL,
  status text NOT NULL CHECK (status IN ('pending', 'verified', 'expired')),
  idempotency_key text NOT NULL,
  request_fingerprint bytea NOT NULL,
  expires_at timestamptz NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (user_id, idempotency_key)
);

The unique constraint turns a race into a recoverable conflict. Store only a token digest, not the usable token. On verification, require status = 'pending' and expires_at > now() in the update predicate. If zero rows are updated, return a generic expired-or-invalid response.

Idempotency records also need retention. Expiring keys too quickly causes a late network retry to create a second request; retaining them forever bloats the table. The right window depends on client retry behaviour, but it should be longer than the maximum expected request timeout and queue delay. A scheduled cleanup job can remove old keys after the window, while the verification request itself keeps its audit state.

Keep email delivery separate from API completion

Do not send an email halfway through a transaction and then report success only after the database commit. A crash between those steps creates an email with no durable request, or a retry that sends a second message.

The outbox pattern is a better boundary: write the verification row and an email.send event in one transaction, then let a worker deliver the message. The worker should have its own delivery idempotency key. Email providers may still retry, so the message path needs a provider receipt and a bounded retry policy.

That separation also makes rate limiting clearer. Limit new commands per user and address, then separately limit delivery attempts. A disposable email address or a throwaway email generator can help isolated staging flows, but it should not bypass production abuse controls.

Testing retries without inbox collisions

Test the state machine, not only the happy path. The minimum suite should cover:

two concurrent requests with one idempotency key;
a retry with the same payload after a simulated timeout;
the same key with a different email;
a token used twice;
an expired token;
an outbox worker retry after a provider timeout;
a verification request for a previously verified address.

For browser coverage, passwordless login email tests are a useful companion pattern. Give each run its own mailbox and message cursor. Never assert that “the newest message” is the right one, because parallel runs make that assumption false pretty quick.

Legacy test data sometimes contains search strings such as tepm mail com or tamp mail com. Keep those as plain fixture text, not as links or API rules. It is easy to confuse a typo keyword with a valid domain when a test is written in a hurry.

A practical checklist

Before shipping the endpoint, check the following:

Is the idempotency key scoped to the user and operation?
Does PostgreSQL enforce uniqueness under concurrency?
Is the request fingerprint checked on replay?
Are tokens hashed, single-use, and time limited?
Can the API commit without waiting for the provider?
Does the outbox worker expose a durable delivery receipt?
Are response messages generic enough for account privacy?
Are old records cleaned without deleting useful audit history?

One small detail is often missed: a verified request should remain verified when a duplicate confirmation arrives. The handler must be monotonic; it shouldnt move the record backward just because the second click used stale state. With these constraints, retries become an expected part of the system rather than an exceptional path, and the email flow stays understandable when production gets busy.

A State Machine for Reliable Email Verification APIs

kevindev — Sun, 04 Oct 2026 05:23:25 +0000

Email verification is often implemented as two columns: an address and a verified boolean. That is enough for a demo, but it becomes vague when a message is delayed, a user requests a second code, or a worker retries after a timeout.

In backend systems I prefer treating verification as a small state machine. The state records what happened, while an attempt record explains when and why it happened. This makes a REST API easier to operate and keeps PostgreSQL as the source of truth instead of scattering decisions through Node.js handlers.

Why a boolean verified flag is not enough

With only verified = false, the API cannot distinguish a new signup from an expired token, a blocked attempt, or a message that was sent but never consumed. Those cases need different responses and different metrics.

There is also a race. A user can click an old link at the same time that a newer verification email is issued. If both requests only update the user row, the older token may win. The result looks valid in the database but does not match the latest user action.

I use an immutable verification attempt for each issued token. The user account keeps the current status, but the attempt keeps its own creation time, expiry time, consumption time, and request identifier. This is a little more data, and a lot less guesswork.

Model the verification lifecycle

A practical lifecycle is:

created -> sent -> verified
            |         
            +-------> expired
            +-------> revoked

The transitions should be explicit. created means the API accepted the request, while sent means the mail provider accepted the delivery request. Those are not the same event. A provider timeout must not silently become verified, and a duplicate send should not create an untraceable second token.

An attempt table can contain fields like these:

CREATE TYPE verification_status AS ENUM
  ('created', 'sent', 'verified', 'expired', 'revoked');

CREATE TABLE verification_attempts (
  id uuid PRIMARY KEY,
  user_id bigint NOT NULL,
  token_digest bytea NOT NULL UNIQUE,
  status verification_status NOT NULL,
  request_id text NOT NULL,
  expires_at timestamptz NOT NULL,
  verified_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);

Store a digest of the token, not the raw token. The raw value belongs in the link sent to the user and should not be recoverable from a database backup. It is also worth indexing (user_id, status, created_at DESC) for the lookup used by support and cleanup jobs.

For email tests, an isolated temporary email account generator can help inspect delivery without using a personal inbox. Keep that fixture separate from production identity data, and give it a short expiry.

Enforce transitions in PostgreSQL

Do not rely on every application path remembering the same rules. A verification transaction should lock the selected attempt, check its status and expiry, then update it atomically:

UPDATE verification_attempts
SET status = 'verified', verified_at = now()
WHERE id = $1
  AND status = 'sent'
  AND expires_at > now()
RETURNING id, user_id;

If this returns no row, the caller must treat the token as already used, expired, or unknown. That single result is safer than reading first and updating later. The user status update should happen in the same transaction, so a crash cannot leave the attempt verified while the account remains pending.

When several workers process delivery callbacks, use a request ID with a unique constraint. The notes on concurrency keys for email checks are relevant here: concurrency control needs an owner and a durable key, not only a timing assumption.

Make the REST API retry-safe

The Node.js endpoint should return a stable outcome for a repeated request. For example, POST /v1/email-verifications can accept an Idempotency-Key, store the request result, and return the original attempt when the same key is retried. The handler should not send a second message just because the client did not receive the first HTTP response.

The confirmation endpoint can use these categories:

204 when the token is accepted.
409 when the attempt was already consumed or revoked.
410 when the token is expired.
404 when the token is unknown, without revealing whether an account exists.

The exact contract is a product decision, but it should be documented and tested. My earlier approach to idempotent signup email handling follows the same boundary: retries should replay a known result, not create side effects again.

Some old test fixtures still contain the phrase temp org mail. Keep that as plain text if it is needed to identify legacy data; it should never be a URL, a token, or a backlink anchor. Small naming mistakes in fixtures are easy to chase for hours.

A production checklist

Before shipping, check that:

Every token has an expiry and a digest, not a plaintext value.
State transitions are guarded by the current status and performed transactionally.
Send requests have an idempotency key and a durable request result.
Repeated confirmation requests have documented, stable responses.
Cleanup marks stale attempts as expired and records counts for monitoring.
Logs contain request IDs and attempt IDs, but not email tokens.

This design is not a large workflow engine. It is a narrow state machine around a security-sensitive action. That boundary gives the API clear behavior under retries, delayed mail, and concurrent clicks, which is what a boolean flag cannot provide.