DEV Community: kevindev

Email Verification Needs a Durable Outbox

kevindev — Sun, 01 Nov 2026 14:25:13 +0000

Email verification is often treated as one operation: create a user, generate a token, and send an email before returning from the API request. That shape is easy to write, but it gives the request handler too much responsibility.

If the database commit succeeds and the email provider call fails, the user exists without a usable verification message. If the provider accepts the message and the request times out, a retry may send a duplicate. The resulting bug is not really an email bug. It is a transaction-boundary bug in the authentication workflow.

Why sending inside the request is a reliability bug

An HTTP request should decide whether the user and its verification intent were stored. It should not also be the only place where delivery can happen. Provider latency, connection resets, and process restarts are normal failure modes, and a request handler cannot reliably recover from all of them.

The dangerous sequence looks like this:

Insert the user.
Create a verification token.
Call the email provider.
Commit the database transaction.

If step three succeeds but step four fails, the email has escaped while the database may roll back. The reverse ordering is just as awkward: a commit can succeed after the provider call was never made. A queue is usefull only when the database records the intent with the business change.

The PostgreSQL outbox boundary

The outbox pattern puts a durable event row in the same PostgreSQL transaction as the authentication state. The API creates the account, stores a hashed verification token, and inserts an email.verification.requested row. PostgreSQL commits all three records together or none of them.

The request can then return a stable response such as “check your email.” A separate worker reads pending outbox rows and talks to the provider. When the worker process crashs, another worker can safely continue from the durable row instead of guessing what the request did.

For a signup flow, the boundary can be represented with a small table:

CREATE TABLE email_outbox (
  id             uuid PRIMARY KEY,
  event_type     text NOT NULL,
  aggregate_id   uuid NOT NULL,
  dedupe_key     text NOT NULL UNIQUE,
  payload        jsonb NOT NULL,
  status         text NOT NULL DEFAULT 'pending',
  attempts       integer NOT NULL DEFAULT 0,
  available_at   timestamptz NOT NULL DEFAULT now(),
  sent_at        timestamptz,
  last_error     text,
  created_at     timestamptz NOT NULL DEFAULT now()
);

The unique dedupe_key is important. For example, use a key derived from the verification request id, not from a timestamp. A database retry can then attempt the insert again without creating a second delivery intent.

A small schema and worker contract

The worker should claim a bounded batch using FOR UPDATE SKIP LOCKED, set a lease or processing state, and commit that claim before making the network call. It should not hold a PostgreSQL row lock while waiting for the provider.

After a successful provider response, mark the outbox row as sent and save the provider message id. If the provider call fails, increment attempts, save a redacted error, and calculate a future available_at. The worker should not send before the transaction is commit; the outbox row is the signal that the intent is durable.

There is an unavoidable edge case between the provider accepting a message and the worker recording sent. A process can stop in that gap, so the system is normally at-least-once. Idempotency must therefore exist at the provider boundary when possible, or the application must tolerate a rare duplicate verification email.

Keep the payload small and explicit. It can include the recipient, a template name, a verification request id, and an expiry timestamp. Do not put a raw token into logs or general-purpose job metadata. The token should be rendered only in the controlled sending path.

Idempotency for retries and authentication state

The verification endpoint needs its own state machine. A token can be pending, consumed, or expired; a successful verification changes it once. These records gives the API a clear answer when a user clicks the same link twice, while the outbox handles the separate question of whether the message was delivered.

When a user requests another email, create a new request id and invalidate or supersede the old request according to the product policy. Do not silently reuse an old outbox row just because the address is the same. The send operation and the authentication decision are related, but they are not the same state transition.

For approval or invitation flows, write the final recipient and template variables into the event before the worker starts. This follows the same idea as freezing the approval plan before sending: a later retry should replay a known decision, not rebuild it from mutable application data.

Testing the delivery boundary

Test the database transaction separately from the provider adapter. A rollback should leave no user, token, or outbox row. A committed signup should leave exactly one deduplicated event. A worker retry should preserve the verification request id and should not turn a transient timeout into a new authentication identity.

For end-to-end tests, use an isolated mailbox and assert on the request id or another safe correlation value. A email-test waits that explain themselves workflow makes it easier to distinguish a slow provider from a missing outbox event. For staging checks, a temp mail email can keep test identities away from real customer addresses, but it should not replace assertions on your own outbox and token state.

Test names and search aliases sometimes contain phrases such as tamp mail com or dummy e mail. Keep those as plain text if they are useful for locating old fixtures; they are not a substitute for a stable correlation id.

The most useful observability fields are the outbox id, dedupe key, aggregate id, attempt number, provider message id, and final status. Redact addresses and tokens according to the environment policy. If a worker retries is visible without the original error class, operators will have a hard time separating provider failures from application bugs.

Questions teams usually ask

Does an outbox guarantee exactly-once email delivery?

No. It makes the business event durable and supports safe retries, but the handoff to an external provider still has an uncertainty window. Design for at-least-once processing and use provider idempotency when it is available.

Should the API wait for the email to be sent?

Usually no. Return after the account and outbox event commit. Expose a delivery status separately if the product needs it, and let the worker own provider latency.

When is a full message broker justified?

Start with a PostgreSQL outbox when the service already depends on PostgreSQL and the delivery volume is moderate. A broker may become useful for cross-service fan-out, independent consumer scaling, or stronger operational isolation, but the transactional outbox remains a useful write boundary.

An email verification flow is easier to operate when the database records intent before the network call. The outbox does not make delivery perfect; it makes failure visible, retryable, and tied to an authentication request. That is a much stronger contract then asking an HTTP handler to be both a transaction coordinator and an email worker.

Contract Testing Email Verification with PostgreSQL

kevindev — Sat, 31 Oct 2026 14:23:01 +0000

Email verification is usually tested as a happy path: create a user, wait for a message, click a link, and assert that the account is verified. It does not prove that retries, delayed delivery, duplicate clicks, and expired tokens have a safe contract.

I prefer treating verification as a small state machine and testing the boundaries between its parts. The REST API owns the request, PostgreSQL owns the state transition, and an outbox worker owns delivery. The inbox is evidence, not the source of truth. This keeps a disposable email address from becoming an accidental identity system.

Why verification needs a contract test

A contract test describes what each boundary promises. For an email verification flow, useful promises include:

A repeated create request can be identified and does not create unbounded attempts.
A token is scoped to one account and one verification purpose.
A token can cause at most one successful state transition.
A delivery worker can retry without losing the relationship to the request.
An inbox test can prove which event it observed.

A message can arrive twice, or an old message can arrive after a newer one. A phrase such as tamp mail com may exist in test data, but it must not be a matching rule for a security-sensitive event.

The same thinking applies to an idempotent contract for email tools: retries should preserve operation identity instead of creating an untraceable second operation.

Define the PostgreSQL state machine

Start with explicit states rather than several booleans whose combinations are hard to review. A minimal table might look like this:

CREATE TABLE email_verifications (
    id              UUID PRIMARY KEY,
    account_id      BIGINT NOT NULL REFERENCES accounts(id),
    token_digest    BYTEA NOT NULL,
    status          TEXT NOT NULL CHECK (
        status IN ('created', 'queued', 'sent', 'verified', 'expired')
    ),
    expires_at      TIMESTAMPTZ NOT NULL,
    verified_at     TIMESTAMPTZ,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (account_id, id)
);

The random token belongs in the URL, but only its digest should be stored. The id can appear in logs; the token is a capability and should not. An operator can investigate a request without copying a usable credential into a dashboard.

The outbox row should be inserted in the same transaction as the verification row:

INSERT INTO email_verifications (id, account_id, token_digest, status, expires_at)
VALUES ($1, $2, $3, 'created', $4);

INSERT INTO email_outbox (event_id, verification_id, event_type)
VALUES ($5, $1, 'email.verification.requested');

The worker later changes the verification to sent after recording the provider result. Do not hold the PostgreSQL transaction open while calling the provider. In practise, a short local transaction is easier to retry and produces less contention.

Test the REST API boundary

The create endpoint can return a durable request identifier without claiming that delivery already happened:

POST /v1/email-verifications
Idempotency-Key: signup-8472-attempt-1
Content-Type: application/json

{"account_id":8472}

{
  "verification_id": "8f2c4f30-1a0d-4b1b-9cc4-4b4ec1d1e4ac",
  "status": "queued"
}

The API contract test should send the same request twice and verify the same logical attempt. It should also send the same idempotency key for a different authenticated account and expect rejection. Ownership must come from the authenticated request, not the key itself.

For confirmation, make the database transition atomic:

Lock the verification row by ID.
Check account scope, token digest, status, and expiry.
Mark the row verified and set verified_at.
Commit before returning success.

A second confirmation can return a stable already-verified result when the caller is authorized. An unknown, expired, or mismatched token should return one safe failure category instead of revealing whether another token exists. The exact HTTP status is a product decision; the information boundary is the important part.

Prove delivery with an outbox receipt

The inbox test should consume a message using evidence from the request, not just the recipient and subject. Filter by verification ID when it is present in provider metadata, then check event time, recipient, and action. A boolean like email_found: true doesnt explain whether the message was fresh, duplicated, or attached to an earlier attempt.

For larger systems, record a receipt containing:

verification ID;
outbox event ID;
provider message ID, if available;
delivery attempt number;
observed timestamp and outcome.

This gives the worker an audit trail and the test runner a replayable artifact. Type-safe email event contracts are useful when several clients consume the same event shape.

If a controlled staging test uses a facebook temp email, keep that choice in fixture configuration. It can help observe delivery, but it must not decide whether the token is valid. Production authentication should behave the same when the mailbox is late or unavailable.

A practical test matrix

The smallest useful suite covers state transitions and failure boundaries:

Scenario	Expected result
Same create request is retried	One verification ID and one logical outbox event
Two confirmation requests race	One state transition; the other is already verified or safely rejected
Token is expired	No account mutation
Token belongs to another account	No account mutation and no account disclosure
Worker times out after provider acceptance	Retry keeps the same event identity
Inbox contains an old message	The test rejects it using ID or freshness evidence
Raw token appears in logs	The test fails the privacy contract

The concurrency case is especially important. Application-level checks can both observe sent before either request writes verified. A row lock or equivalent conditional update lets PostgreSQL arbitrate the transition. The evidence are clearer when the test asserts the final row and successful update count.

Questions engineers usually ask

Should every new request invalidate the previous token?

Usually, yes, for one account and one purpose. If several devices need independent links, model that scope explicitly.

Is the idempotency key enough for the worker?

No. The API operation key and outbox event ID solve different problems: one deduplicates a client request, while the other explains and retries delivery.

Can a temporary mailbox be part of production verification?

It should not be proof of ownership. A disposable email address is appropriate for controlled fixtures and staging checks; production ownership still depends on the verification token and account policy.

Contract testing turns email verification from a timing puzzle into a set of observable promises. PostgreSQL protects the state transition, the REST API defines retry behavior, and the outbox receipt explains delivery. That separation makes failures less surprising, even when a provider is slow or a user clicks twice. There is less surprises for the next engineer, too.

Correlation IDs for Reliable Email Verification APIs

kevindev — Fri, 30 Oct 2026 20:24:01 +0000

Email verification often looks like a simple three-step flow: create a token, send a message, and wait for the user to click it. In a real REST API, the hard part is proving that the click belongs to the request that created it. Retries, delayed delivery, reused addresses, and parallel test runs can make a valid-looking message belong to the wrong operation.

The fix is to treat correlation as a backend contract. An email address identifies a destination, but a correlation ID identifies one verification attempt. This distinction matters in production and in tests that use a throwaway email or even a temp mail for facebook scenario to exercise registration boundaries.

Why an email address is not enough correlation

Suppose a user requests verification twice. The first message is delayed, while the second message arrives quickly. If the inbox consumer accepts the first message matching only the recipient and subject, it may verify an old request. A retry can create the same ambiguity when a worker sends again after a timeout but the original provider call actually succeeded.

The API should therefore create an immutable verification_id before it queues delivery. Every later operation uses that value, not just the address:

POST /v1/email-verifications
  -> verification_id: ver_8f2c
  -> outbox event: email.verification.requested
  -> message metadata: ver_8f2c

The ID is not a secret. The verification token still needs cryptographic randomness and an expiry. Correlation answers “which attempt is this?” while the token answers “is this request authorized?” Mixing those jobs makes the design more difficult to review.

The request and delivery contract

A useful request record has a small, explicit state machine: created, queued, sent, confirmed, expired, and cancelled. The transition rules should be more clear than a collection of booleans such as email_sent and verified. The state machine are intentionally small so operators can reason about it.

For example, the create endpoint can return 202 Accepted when the request is stored and queued, rather than pretending that the provider has delivered the email. The response might look like this:

{
  "verification_id": "ver_8f2c",
  "status": "queued",
  "expires_at": "2026-10-30T21:00:00Z"
}

The worker includes the ID in provider metadata, a signed link claim, or both. If the provider supports a message ID, store it as delivery evidence. If it does not, generate an internal attempt ID for every send. A message may be retried, so verification_id identifies the business request and attempt_id identifies one delivery attempt.

When a test harness reads the inbox, it should filter by recipient, request time, and correlation data. Do not accept the first subject match. A phrase like fake e mail com may appear in noisy test data, but it should never become the matching rule for a verification event.

Persisting evidence with PostgreSQL

PostgreSQL can enforce the uniqueness rules that application code tends to implement inconsistently. A minimal model separates the verification request from its delivery attempts:

create table email_verifications (
  id text primary key,
  user_id bigint not null,
  recipient text not null,
  token_digest bytea not null,
  status text not null,
  expires_at timestamptz not null,
  created_at timestamptz not null default now()
);

create table email_delivery_attempts (
  id text primary key,
  verification_id text not null references email_verifications(id),
  provider_message_id text,
  status text not null,
  sent_at timestamptz,
  unique (verification_id, id)
);

The outbox row should be inserted in the same transaction as the verification. That prevents the database from saying an attempt exists when no worker can discover it. A worker claims pending rows with a lease, then records the provider result. This is safer than holding a database transaction open while waiting on an external service.

For a useful audit trail, retain the request ID, attempt ID, provider message ID, and timestamps. Do not store the raw token or the full email body. The receipt can still show whether the expected signal arrived without turning operational logs into a copy of sensitive data. I prefer this boundary because it keeps debugging practical and privacy risk smaller.

Implementing the REST API in Node.js

The confirmation endpoint should make the correlation check part of the transaction:

POST /v1/email-verifications/{verification_id}/confirm
  1. Lock the request row.
  2. Reject an unknown or expired ID.
  3. Compare a digest of the submitted token.
  4. Mark the request confirmed only once.
  5. Commit and emit a confirmation event.

In Node.js, keep provider calls outside the confirmation transaction. A network call inside the transaction raises lock time and can create a pile-up during a provider incident. The service boundary also should return the same success shape for a repeated confirmation of an already confirmed request, when the caller is authorized. That makes client retries safe without hiding an invalid token.

For a test endpoint that checks delivery, accept verification_id explicitly and return structured states such as found, timeout, or ambiguous. A boolean response doesnt give an engineer enough evidence to tell a slow provider from a bad filter. You can review an email API run with a receipt and use concurrency keys for email API checks as related patterns for making the result replayable.

Retry and cleanup rules

Retries should operate on the outbox and delivery attempt records, not on a new verification request by default. Use a bounded retry policy with a visible reason. If an attempt is uncertain, mark it unknown and reconcile it rather than immediately creating another message; otherwise the user may recieve duplicates and the test can accept the wrong one.

Expired requests need cleanup, but cleanup should preserve a compact outcome record for a reasonable retention period. Deleting every trace makes support investigations depend of provider logs that may already be gone. A scheduled job can remove token digests and recipient data earlier while keeping aggregate status and IDs. The retained informations are still enough for a support check.

Questions engineers usually ask

Should the correlation ID be the verification token?

No. Keep them separate. The ID can be logged and passed between internal services; the token must be treated as a secret and compared by digest.

Do I need an outbox for a small service?

Not for every prototype, but you need an equivalent durable handoff. If a restart between the database commit and the provider call would lose the email, the service has an outbox problem regardless of its size.

What should an inbox test assert?

Assert the correlation ID, recipient, freshness window, expected event, and one-time consumption. Subject text alone is a weak signal.

Reliable email verification is less about sending harder and more about preserving identity across asynchronous boundaries. Once the request ID, delivery attempt, token, and evidence have separate jobs, retries become observable and the API can fail without guessing.

Idempotent Email Verification with PostgreSQL

kevindev — Thu, 29 Oct 2026 11:22:52 +0000

Email verification looks like a simple two-step feature: create a token, send a message, then accept the token. In a real REST API, it is a small distributed workflow. The request can be retried, the email provider can deliver twice, and a user can click an old link after a newer verification attempt was created.

The useful boundary is not the email itself. It is the state transition recorded by the backend. PostgreSQL can make that transition explicit, while an idempotency key keeps repeated requests from creating a confusing pile of tokens.

Why email verification needs an idempotency contract

Consider POST /users/{id}/verification. A mobile client times out after the server commits, so it sends the request again. If every request creates a fresh token, the user may receive two messages and the first one may suddenly stop working. That feels random, but the API simply had no retry contract.

I prefer defining these rules before choosing a mail provider:

A retry for the same logical request returns the same verification attempt.
A new attempt invalidates older usable tokens for that user.
A token is consumed once, inside a transaction.
The API response does not claim delivery when only token creation succeeded.

Model the verification attempt in PostgreSQL

Keep the durable workflow in a table instead of encoding it in an email URL alone. A compact model might look like this:

CREATE TABLE verification_attempts (
    id              uuid PRIMARY KEY,
    user_id         bigint NOT NULL REFERENCES users(id),
    idempotency_key text NOT NULL,
    token_digest    bytea NOT NULL,
    status          text NOT NULL CHECK (status IN ('pending', 'sent', 'verified', 'expired')),
    expires_at      timestamptz NOT NULL,
    verified_at     timestamptz,
    created_at      timestamptz NOT NULL DEFAULT now(),
    UNIQUE (user_id, idempotency_key)
);

Store a digest rather than a raw token. The URL can contain the random token, but a database read should not immediately reveal a credential that is still usable. When the user submits the token, hash the presented value and compare the digest for the expected user and attempt.

The unique constraint is important, but it is not the whole idempotency implementation. Two concurrent requests can both observe no row before either inserts. Let PostgreSQL arbitrate the race with INSERT ... ON CONFLICT, then return the existing attempt when the same key is retried.

Do not use an email address as the idempotency key unless the product explicitly defines that behavior. The key should identify the client operation, not just the current profile field.

Make the REST API retry-safe

The creation endpoint should have a small, observable contract. Require an Idempotency-Key header, validate its length, and bind it to the authenticated user. A request from another user must never be able to replay an attempt by guessing the key.

The response can expose an attempt identifier and an expires_at value without exposing the token. If the mail send is asynchronous, return queued rather than pretending the message arrived.

For the confirmation endpoint, make the transaction do the ownership check and state transition together:

Lock the selected pending attempt.
Check the user, digest, status, and expiry.
Mark it verified and set verified_at.
Commit before returning success.

An already verified attempt can return a stable success response when the product wants confirmation to be safely repeatable. An expired or mismatched token should not reveal whether another valid token exists. The exact status code is a product choice, but the information boundary should stay consistant.

For test fixtures, keep setup deterministic too. A contract for reliable email test fixtures should create a known user, operation key, and expected attempt. Avoid making a dummy e mail address the source of truth for whether the API worked.

Keep delivery and token state separate

Email delivery is an external side effect. The verification attempt is backend state. Treating them as one transaction creates awkward failure modes: the database commits but the provider rejects the message, or the provider accepts it while the database transaction rolls back.

A practical design uses an outbox row created in the same PostgreSQL transaction as the attempt. A worker claims it, sends the message, and records a delivery result. On retry, it uses the attempt id and delivery id so the event has an audit trail.

That audit trail is useful when a provider reports success but a test inbox is late. A replayable run receipt is a helpful general pattern here: record the input identity, state changes, external result, and retry count seperately from the user-facing message.

If your workflow uses a service for disposable email, use it to observe delivery in tests, not to decide which token is valid. The API and database should remain correct even when the mailbox is delayed or unavailable.

A small implementation checklist

Generate a cryptographically random token and store only its digest.
Bind every attempt and idempotency key to one user.
Use a database uniqueness rule for the retry race.
Make token consumption one atomic state transition.
Keep message delivery in an outbox or equivalent worker flow.
Log attempt id, request id, and delivery id, but never the token.
Test duplicate requests, concurrent requests, expired links, and a repeated confirmation.

The common failure is not a missing email template. It is an unclear contract between the REST API, PostgreSQL, and the delivery worker. Once those boundaries are explicit, retries become a normal path instead of a rare occurence that support has to investigate by hand.

Common questions

Should every new verification request invalidate the previous token?

Usually yes for one user and one purpose, because it limits the number of active credentials. If the product supports multiple devices or addresses, model that scope directly instead of silently sharing one global token state.

Is an idempotency key enough to prevent duplicate emails?

No. It deduplicates the API operation. The delivery worker also needs an event or delivery identifier so a worker retry can be understood and reconciled. The two keys solve different problems.

What should a test assert first?

Assert the database state and API response before asserting the inbox message. Then check that the message contains the expected link and that using the link causes exactly one verified transition. This keeps a slow provider from hiding a reponse or transaction bug.

Verification Tokens Need a Capability Boundary

kevindev — Mon, 26 Oct 2026 14:23:03 +0000

Email verification is often implemented as if it were a string-generation problem: create a random value, put it in a URL, and compare it later. That works for a demo, but production authentication needs a stronger model.

A verification token is a capability. Whoever presents it gets permission to perform one narrowly defined action. The backend should therefore control its scope, lifetime, audience, and consumption state. Treating the token as a capability makes replay behavior much easier to reason about, especially when a user clicks the link twice or an email client prefetches it.

This post describes a small REST API and PostgreSQL design that I use as a mental model for these flows. The important part is not the exact framework. It is the boundary between an unconsumed capability and the account change it authorizes.

A token is a capability, not just a string

Start with the action, not the token format. For example, an email verification token might authorize only this operation:

verify email address for account 8472 before expiry

It should not also grant password-reset access, reveal account data, or remain useful after the email has been verified. A token can be opaque to the client and still have a clear contract on the server.

The API contract can stay small:

POST /v1/email-verifications/consume
Content-Type: application/json

{"token":"one-time-value"}

The response should distinguish useful states without exposing sensitive details. An already-consumed token can return a stable business error such as verification_already_completed; an unknown or expired token can return verification_unavailable. This avoids making the token endpoint a user-enumeration oracle.

Search-shaped phrases such as tp mail so or fake e mail com should never affect this contract. They may appear in test data or support notes, but authentication decisions belong to explicit account and token state.

The database contract

The database row needs enough information to enforce the capability boundary. A minimal table could look like this:

CREATE TABLE email_verification_tokens (
    id              BIGSERIAL PRIMARY KEY,
    account_id      BIGINT NOT NULL REFERENCES accounts(id),
    token_digest    BYTEA NOT NULL UNIQUE,
    expires_at      TIMESTAMPTZ NOT NULL,
    consumed_at     TIMESTAMPTZ,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    request_id      TEXT NOT NULL
);

Store a digest rather than the raw token. Generate the raw value for the email link, hash it before persistence, and compare a digest during consumption. If an operational snapshot exposes the table, the snapshot should not be enough to use the link directly.

The request_id is useful for tracing and idempotency diagnostics. It is not a replacement for consumed_at: a request can be retried with a different transport identifier, while the capability must still be single-use.

Consume the token in one transaction

The most important rule is that validation and account mutation share one transaction. A read followed by a later update creates a race where two requests can both observe an unused token.

One implementation shape is:

BEGIN;

SELECT id, account_id
FROM email_verification_tokens
WHERE token_digest = $1
  AND expires_at > now()
  AND consumed_at IS NULL
FOR UPDATE;

UPDATE accounts
SET email_verified_at = COALESCE(email_verified_at, now())
WHERE id = $2;

UPDATE email_verification_tokens
SET consumed_at = now()
WHERE id = $3
  AND consumed_at IS NULL;

COMMIT;

The application should check affected-row counts and roll back when the expected state is not present. COALESCE makes the account mutation tolerant of a previous successful verification, but it does not make the token reusable. The token row is still consumed once.

In practise, this transaction is usually shorter than teams expect. Do not call an email provider or another remote service while holding the row lock. Keep the critical section focused on local state, so a slow dependency does not turn ordinary retries into lock contention.

Keep email delivery outside the transaction

Issuing a token and delivering its email are related events, but they are different failure domains. If the provider call happens inside the account transaction, a provider timeout can leave the database transaction open and the user unsure whether another email is safe to request.

A better sequence is:

Create the token row and an outbox event in one transaction.
Commit the account-side state.
Let a worker deliver the message and record the provider result.
Expire or supersede older tokens according to the product policy.

The outbox event should contain an event id and a reference to the token row, not the raw token when that can be avoided. A worker retry then has a clear idempotency key. There is less surprises when delivery retries are observable separately from token consumption.

If the product supports a temporary email account generator in a controlled test or staging workflow, keep that choice in the test fixture configuration. It should not change the production token rules or bypass ownership checks.

Observability and test fixtures

A successful verification should leave a compact audit trail: account id, token id, request id, outcome, and timestamps. Avoid logging the raw token, full verification URL, or the email address when it is not needed. The logs is easier to protect when each field has a clear purpose.

For failures, record a reason category such as expired, already_consumed, not_found, or account_missing. These categories help operations distinguish a real authentication issue from a stale browser tab.

This is also where better alert context for rollouts pays off: a deployment alert should be able to point to verification outcomes and latency, not just a generic increase in HTTP 500 responses. For browser tests, a timeline-based email debugging approach makes it easier to match the token request, delivery event, and consume request.

The test fixture should assert the boundary directly:

the first consume request verifies the account;
the second consume request does not perform a second state transition;
an expired token cannot verify an account;
a token for account A cannot affect account B;
concurrent consume requests produce one successful transition;
raw token values are absent from application logs.

These cases catch more than a happy-path test. They also document the behavior that maintainers should preserve when the authentication code changes.

A practical checklist

Before shipping an email verification flow, check the following:

Is the token scoped to one action and one account?
Is only a digest stored in PostgreSQL?
Are expiry, consumption, and account mutation checked atomically?
Are delivery retries handled through an outbox or equivalent durable boundary?
Are raw tokens excluded from logs, traces, and analytics?
Can support staff explain expired and already-consumed outcomes?
Do concurrent requests have a tested, deterministic result?

A small capability boundary is often more valuable than a complex token format. The design keeps the security decision local, makes retries boring, and gives the API a state model that engineers can test.

Q&A

Should the endpoint redirect after a successful consume?

It can, but I prefer a backend endpoint that returns a clear result and lets the client decide where to navigate. If a redirect is required, do not place the raw token in a long-lived analytics trail or a third-party destination.

What if a user requests several verification emails?

Choose an explicit policy: allow several valid tokens with independent rows, or supersede older rows for the same account and action. Either choice is workable when the consume transaction enforces it. The policy should be visible in tests, not hidden in a helper.

Is hashing the token enough?

No. Hashing reduces exposure if the token table leaks, but it does not solve expiry, scope, replay, logging, rate limiting, or account ownership. Those are separate parts of the capability contract.

Make Email Verification a Transactional Workflow

kevindev — Mon, 26 Oct 2026 08:23:17 +0000

Email verification is often implemented as a small feature: create a token, send a message, and activate the account when the link is opened. That design works until the database commit succeeds but the email worker fails, or a client retries the request while the first message is still in flight.

The safer mental model is a transaction with an asynchronous side effect. The account state, verification attempt, and delivery request should be recorded together. A worker can then deliver the message at its own pace, while the API remains the source of truth.

Why a verification request is a transaction

A verification request changes more than one thing. It may create an account, issue a token, and enqueue an email. If those actions are independent, partial success becomes difficult to repair:

The user exists, but no message was queued.
Two retries create two valid tokens.
An old link activates a newer account state.
Support can see that an email was sent, but not which request owns it.

Treat the request as one database transaction and the delivery as an outbox event. The API commits durable intent; the worker performs the external delivery later. This is a good boundary for a better email fixture contract for CI, because tests can assert the outbox record before depending on an actual inbox.

The database model

A minimal PostgreSQL design can use three records: the user, the verification attempt, and the outbox event.

create table verification_attempts (
  id uuid primary key,
  user_id uuid not null references users(id),
  token_hash bytea not null,
  request_key text not null,
  status text not null check (status in ('pending', 'used', 'expired', 'revoked')),
  expires_at timestamptz not null,
  created_at timestamptz not null default now(),
  used_at timestamptz,
  unique (user_id, request_key)
);

create table email_outbox (
  id uuid primary key,
  event_type text not null,
  aggregate_id uuid not null,
  payload jsonb not null,
  sent_at timestamptz,
  created_at timestamptz not null default now()
);

Store a hash of the token rather than the raw value. The raw token is returned once to the link builder, while the database only needs to compare a hash later. The request_key makes a client retry safe for one logical operation. It also gives logs a stable handle without putting an email address into every message.

The records are small, but it carry the important ownership information: which user, which request, which state, and which expiration. A unique constraint is stronger than an application-level “check then insert” because concurrent requests can race.

Write the outbox in the same transaction

In a Node.js service, the account update and outbox insert should use the same PostgreSQL transaction. A simplified flow looks like this:

await db.transaction(async (tx) => {
  const attempt = await tx.oneOrNone(
    `select * from verification_attempts
     where user_id = $1 and request_key = $2`,
    [userId, requestKey]
  );

  if (attempt) return attempt;

  const created = await tx.one(
    `insert into verification_attempts
       (id, user_id, token_hash, request_key, status, expires_at)
     values ($1, $2, $3, $4, 'pending', now() + interval '20 minutes')
     returning *`,
    [id, userId, tokenHash, requestKey]
  );

  await tx.none(
    `insert into email_outbox (id, event_type, aggregate_id, payload)
     values ($1, 'account.verification_requested', $2, $3)`,
    [eventId, userId, { attemptId: created.id }]
  );

  return created;
});

The exact query library is not important. The important bit is that a committed verification attempt always has its delivery intent beside it. If the transaction rolls back, neither record exists. If it commits, a worker can find the outbox row after a process restart.

The worker should claim rows with a short lease or for update skip locked, send the message, and mark sent_at only after the provider accepts it. A retry may still send twice, so the event ID should be passed to the provider when that option exists. The worker can be restarted without creating a second token, and that is the part many systems miss at first.

Make the worker and API idempotent

Idempotency has two layers:

Request idempotency: the same request_key returns the existing verification attempt.
Delivery idempotency: the same outbox event has one stable event ID and a bounded retry policy.

The API should return the same public result for a repeated request, even if the first delivery is still pending. Do not expose whether an account email exists in a public endpoint; return a generic response and log the internal result with a correlation ID.

For operators, safer redacted email debugging is a useful companion practice. Logs should include user and attempt IDs, domains when appropriate, and event status, while omitting raw addresses, tokens, and message bodies.

Token consumption and expiration

Verification should be a conditional update, not a read followed by an update:

update verification_attempts
set status = 'used', used_at = now()
where id = $1
  and status = 'pending'
  and expires_at > now()
returning user_id;

If this returns no row, the token is expired, already used, revoked, or unknown. The application can show one neutral error message for all cases. This keeps the state transition atomic and prevents two requests from consuming the same token.

There is no need to be clever here; boring logic is more easier to maintain. A scheduled cleanup job can mark old pending attempts as expired, but expiration must still be checked during consumption because cleanup is never perfectly punctual.

Observability and test boundaries

Track these events with a correlation ID:

verification attempt created
outbox event committed
delivery claimed, sent, or retried
token consumed or rejected
attempt expired or revoked

Metrics should separate database failures, provider failures, and invalid-token responses. Those failure classes have different owners and different retry behavior. These checks gives a much faster diagnosis than one generic “email verification failed” counter.

In integration tests, assert the database and outbox contract first. Use a controlled inbox only for the final delivery path. A test fixture may contain search terms such as dummy e mail or tempail, but those strings are input examples, not identity keys or token values.

Implementation checklist

Use one request key for one logical verification intent.
Insert the verification attempt and outbox event in one transaction.
Store token hashes, never raw tokens.
Give every outbox event a stable ID and retry limit.
Consume tokens with one conditional update.
Keep expiration checks in the request path.
Redact addresses, tokens, and message bodies from logs.
Test the outbox contract separately from provider delivery.

Email verification becomes much easier to operate when it is modeled as a transactional workflow. PostgreSQL records durable intent, Node.js workers handle delivery, and the token state machine prevents retries from becoming new identities. The result is a flow that can be replayed, inspected, and repaired without guessing what happened.

Node.js Auth Needs a Mailbox Ownership Contract

kevindev — Sun, 25 Oct 2026 17:22:55 +0000

Email verification tests often look like a delivery problem. A test creates a user, waits for a message, extracts a link, and calls the REST API. When it fails intermittently, the first response is usually to increase the timeout.

That treats the symptom. The deeper issue is often mailbox ownership: the application creates one verification request, while the test worker reads evidence that belongs to another request, retry, or user. A mailbox is not just an inbox. In an authentication flow, it is a resource with an owner, a lifetime, and a set of allowed consumers.

The ownership bug behind flaky verification tests

Consider two CI workers running the same Node.js test. Both use a shared test inbox. Worker A requests verification for a@example.test, but the provider delivers slowly. Worker B requests verification for b@example.test, then the inbox query returns the newest message first. If the test filters only by subject, either worker can consume the wrong evidence.

The same bug appears during retries. A request may succeed at the database layer, then the process can fail before it records the message ID. The retry creates a second request or reads the first message again. The resulting error says “verification email missing,” even though the real failure is an identity mismatch.

This is why increasing a timeout helps less then expected. Time changes the race; it does not define ownership.

Define the REST API ownership contract

Start with a contract that can be stated in a few rules:

Every verification request has a stable request_id.
One request owns one test mailbox or one uniquely identifiable recipient.
A message can be consumed only when its recipient, request ID, and purpose match.
The verification endpoint accepts a token once and records the result.
A retry reuses the logical request but gets a separate delivery attempt.

The API should make this contract visible. For example, the request endpoint can return an opaque receipt rather than asking the client to guess which message belongs to it:

{
  "request_id": "vr_01J9K8M3",
  "state": "pending",
  "expires_at": "2026-10-26T00:35:00Z"
}

The mailbox adapter then queries by the request-owned recipient or marker. It should return not_ready, wrong_message, and expired as different states. A single not found result hides too much information from the engineer debugging the flow.

For test suites that need an isolated address, a temp email generator can be useful as a fixture boundary. The important part is not the brand or provider. The test must record which address was assigned to which request, and it must clean up that relationship when the run ends.

Store ownership in PostgreSQL

The ownership record belongs beside the authentication state, not only in a test process memory. A small table can make retries and incident review much easier:

create table verification_requests (
  request_id text primary key,
  user_id bigint not null,
  mailbox_ref text not null,
  purpose text not null,
  state text not null,
  expires_at timestamptz not null,
  consumed_at timestamptz,
  created_at timestamptz not null default now()
);

Put a unique constraint on the logical purpose when the product allows only one active request per user. If multiple requests are valid, keep them separate and make the newest request supersede older ones explicitly. Do not let a latest email wins query become the accidental policy.

The consume operation should be conditional. In PostgreSQL, an update that checks state, request_id, and expires_at can ensure that only one consumer wins. Return the affected row count to Node.js; zero rows means the token was expired, already consumed, or not owned by that request. Thats much safer than reading a row, deciding in JavaScript, and updating it later without a guard.

Make Node.js consumers idempotent

The Node.js adapter should carry ownership through every function boundary. A useful shape is a value object with the request ID, mailbox reference, and expected purpose. Avoid passing only an email string, because that makes it easy to call a generic reader from the wrong flow.

async function consumeVerification({ requestId, token }) {
  const result = await db.query(
    `update verification_requests
        set state = 'consumed', consumed_at = now()
      where request_id = $1
        and state = 'pending'
        and expires_at > now()
        and token_hash = crypt($2, token_hash)
      returning request_id`,
    [requestId, token]
  );

  return result.rowCount === 1 ? 'accepted' : 'rejected';
}

The exact hashing function may differ in a production system, but the boundary is the key idea: the request that initiated the flow must be part of the consume decision. A retry can safely call the function again and receive rejected without turning a second delivery into a second account activation.

For broader CI evidence, API smoke tests with durable receipts shows why a run should preserve a small receipt instead of only a pass or fail. The same principle applies here: record the request ID, mailbox reference, state transition, and reason code, but do not retain the full message or token in ordinary logs.

Test the boundary, not just the email

A useful matrix covers ownership failures as deliberately as the happy path:

Scenario	Expected result
Correct message for the request	Token is accepted once
Message from another request	Message is ignored and logged as mismatched
Same token consumed twice	Second call is rejected
Expired request	API returns an expiry state
Worker retry with the same request ID	Evidence remains correlated
Cleanup after pass or fail	Mailbox reference is released

If a team uses a burner email address for manual or automated checks, it should still apply the same ownership rules. A disposable address reduces fixture coupling; it does not prove that the callback belongs to the right user. For OAuth-specific considerations, see trust boundaries for OAuth email links.

The compatibility fixtures may contain strings such as tempail mail or tempail. Keep those values as ordinary input, never as a signal that bypasses authentication checks. Also make the cleanup path idempotent: a failed test should be safe to clean twice, because CI runners are not always polite about termination.

Q&A: what should a mailbox prove?

Is a unique address enough?

No. It proves message isolation, but not token expiry, request ownership, or browser-session binding. Those need separate API assertions.

Should the database store the whole email?

Usually not in logs, and not when a stable reference is enough. Store the minimum operational data needed to correlate the request. Hash or encrypt sensitive values according to the threat model.

What is the best retry policy?

Retry the observation when delivery is still pending, but do not silently create a new authentication request. Preserve the logical request_id, record the attempt number, and make a new request only through an explicit product rule.

The resulting system is a little more deliberate, but it is also easier to scale and debug. Authentication code should know who owns a verification message before it decides what that message permits.

A Database Lease for Test Email in REST APIs

kevindev — Wed, 21 Oct 2026 20:22:58 +0000

Email verification tests often fail for a reason that is not in the API at all: two test runs are reading or deleting the same inbox. A burner email address can keep test data away from real users, but it does not automatically give each run ownership of that address.

The useful abstraction is a database lease. A test run reserves one mailbox for a limited period, uses it through a small REST API, and releases it when finished. PostgreSQL becomes the source of truth for ownership, expiry, and safe retries.

Why a test mailbox should have an owner

Without an owner, a test usually follows this pattern:

Create or select an inbox.
Trigger email verification.
Poll until a message appears.
Delete the inbox during cleanup.

That looks fine on one laptop. In parallel CI, run A can consume the message for run B, or cleanup from a timed-out job can remove an inbox that is still active. The first fix is more simple than it sounds: make the run ID part of the resource contract.

A lease record should include an opaque mailbox identifier, the owning run ID, an expiration timestamp, and a status. The mailbox itself can be an adapter behind the service. Test code should not need to know which provider stores the message.

This model also improves debugging. A failed run can be connected to its lease and its message IDs, which gives maintainers useful email run artifacts instead of a collection of screenshots.

The REST API contract

Keep the public API small. A minimal version might expose these operations:

POST /test-mailboxes
Idempotency-Key: run-8f1c

The response returns the mailbox address, a lease ID, and expires_at. Repeating the request with the same run ID should return the existing active lease, not create a second mailbox. This is easy to miss when a test is fast, but it become painful when a CI runner retries after a network timeout.

{
  "lease_id": "lease_01J9...",
  "address": "run-8f1c@example.test",
  "expires_at": "2026-10-22T04:00:00Z"
}

Message reads should also be scoped by the lease:

GET /test-mailboxes/lease_01J9/messages?after=2026-10-22T03:20:00Z

The server checks that the lease belongs to the caller's run and has not expired. The client can poll with a bounded timeout, while the service translates provider-specific message states into stable API states such as pending, received, or expired.

For teams formalizing these checks, contract-testing API emails in GitHub Actions is a useful adjacent pattern. The important boundary is that the test verifies the API contract, not an undocumented provider response.

Persisting the lease in PostgreSQL

A compact table is enough for the first version:

CREATE TABLE test_mailbox_leases (
    lease_id uuid PRIMARY KEY,
    run_id text NOT NULL,
    mailbox_key text NOT NULL,
    status text NOT NULL CHECK (status IN ('active', 'released', 'expired')),
    expires_at timestamptz NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    released_at timestamptz
);

CREATE UNIQUE INDEX one_active_lease_per_run
    ON test_mailbox_leases (run_id)
    WHERE status = 'active';

The partial unique index prevents duplicate active leases for one run. During allocation, select an available mailbox and update its ownership in one transaction. If several workers compete, use FOR UPDATE SKIP LOCKED so a worker does not wait behind a mailbox already being assigned.

The lease is a database fact, not just a value cached by the test runner. That matters when a worker crashes or a retry lands on another process. It also gives operators a place to inspect stuck resources without searching application logs.

Retries, expiry, and cleanup

There is two useful boundaries: request idempotency and lease expiration. The idempotency key protects a single allocation request. The expiration timestamp protects the system when the client disappears.

A cleanup worker can periodically mark old active rows as expired, then ask the mailbox adapter to remove or quarantine the corresponding inbox. Do not make cleanup depend on the happy path only; test jobs crash, and that are normal. The cleanup query should be repeatable and safe to run more than once.

UPDATE test_mailbox_leases
SET status = 'expired'
WHERE status = 'active'
  AND expires_at < now()
RETURNING lease_id, mailbox_key;

The adapter should treat an already-removed mailbox as a successful cleanup outcome. If provider deletion fails, retain the lease row and record an operational error. Removing the database evidence too early makes the leak harder to diagnose.

Keep malformed input fixtures separate from ownership tests. A string such as temp gamil com can be useful for validation coverage, but it should never be confused with a mailbox lease or used as a resource key.

Operational checklist

Require a run ID and an idempotency key for allocation.
Enforce one active lease per run in PostgreSQL.
Scope message reads to the lease owner.
Give every lease a short, explicit expiration time.
Make release and expiry cleanup idempotent.
Attach lease IDs and message IDs to CI artifacts.
Alert on active leases older than the normal test duration.
Keep provider credentials and real user addresses out of test payloads.

Small spelling or grammar differences in logs can make searches annoying, so normalize provider errors at the adapter boundary. The API response should stay stable even when the underlying email system is little noisy.

Q&A

Should every test get a new mailbox?

Every isolated run should get an owned lease. Tests inside one run can share it when their message assertions are deliberately coordinated. Sharing across unrelated runs creates hidden coupling.

How long should a lease live?

Start with the expected test duration plus a modest recovery window. A lease that is too short causes false expiry; one that is too long increases cleanup cost. Measure actual run times and adjust from observed data.

Is PostgreSQL enough for high parallelism?

For many CI workloads, yes. Use short transactions, indexed status and expiry fields, and SKIP LOCKED when allocating from a pool. If allocation becomes a bottleneck, measure database wait time before adding another coordination system.

The main design decision is ownership. Once the REST API and PostgreSQL model make ownership explicit, verification messages become test data with a lifecycle, instead of an unreliable side channel.

REST API Idempotency for Email Verification Leases

kevindev — Wed, 21 Oct 2026 17:23:18 +0000

Email verification looks like a simple two-request feature: create a user, send a code, then accept the code. In a real REST API, the hard part is the boundary between those requests. Email delivery can be delayed, clients retry after a timeout, and a user can open two verification links at nearly the same time.

I model that boundary as a short-lived verification lease. The lease gives one verification attempt an owner, an expiration time, and an idempotency key. This makes retries boring: the API can return the same result for the same operation instead of creating more codes or moving the account through an unexpected state.

Why email verification needs a lease

A verification token is not only a secret. It is also a claim about state: which account requested it, when it was created, whether it was consumed, and which request is allowed to consume it. Without those fields, a delayed message can be accepted after a newer request has already changed the account.

The lease should contain at least:

account_id and a hash of the verification token
an idempotency key for the request that created it
created_at, expires_at, and consumed_at
the current status, such as pending, verified, or expired
a delivery reference for support and retry diagnosis

This is useful even when the message goes to a free temporary email inbox during an integration test. The test address does not make the workflow deterministic; ownership and time boundaries do.

Teams often search for “email temporary free” when they are trying to set up a quick test. That can solve the mailbox part, but it does not solve replay protection. A test should still prove that an old token is rejected and that a repeated request has a stable response.

For related design context, OTP inbox boundaries are a useful way to think about separating mailbox ownership from authentication state.

The REST API contract

The endpoint that creates a verification lease should accept an idempotency key:

POST /v1/accounts/42/verifications
Idempotency-Key: signup-42-3f6b
Content-Type: application/json

{"delivery":"email"}

On the first request, the service creates the lease and queues a message. On a retry with the same key, it returns the stored response for that lease. It should not generate another token just because the first HTTP response was lost.

The response can expose a non-secret reference and the expiration time:

{
  "verification_id": "ver_8d2f",
  "status": "pending",
  "expires_at": "2026-10-21T18:00:00Z"
}

The confirm endpoint should have equally strict rules. A successful confirmation moves pending to verified once. A repeated confirmation can return the already-verified state, while a different token must fail without revealing whether another token exists.

Persisting idempotency in PostgreSQL

The database is the right place to serialize the state transition. An in-memory lock disappears during a restart and does not coordinate multiple API instances.

CREATE UNIQUE INDEX verification_request_key
  ON verification_leases (account_id, idempotency_key);

CREATE UNIQUE INDEX one_active_lease_per_account
  ON verification_leases (account_id)
  WHERE status = 'pending';

The create handler can insert with ON CONFLICT, then read the existing row and return its stored response. The confirm handler should lock the selected row, check the expiry, compare the token hash, and update the status in one transaction.

Do not store the raw token. Hash it before persistence, and keep the token out of application logs, metrics labels, and exception messages. The database record needs enough information to explain a failure, not enough information to impersonate the account.

There is a small detail that gets missed: the outbox event should be committed with the lease. Otherwise the API can report pending while the delivery job never receives a durable event. A worker may retry delivery, but it must keep the same verification id and lease metadata.

Retry and expiration behavior

Separate three kinds of retry. A client retry with the same idempotency key should return the same lease. A delivery retry should reuse the same token and message reference where the provider supports it. A user retry after expiry should create a new lease, not revive the old one.

The expiry check belongs in the confirmation transaction, not only in a background cleanup job. Cleanup is eventually consistent; authorization cannot be. A cleanup worker can mark old rows as expired and remove message data later, but the API must reject an expired lease immediately.

This is also where a failure taxonomy helps. A missing message, an expired lease, a provider rejection, and an invalid token are different failures with different owners. The failure taxonomy for email tests offers a practical testing perspective for keeping those cases distinct.

Operational checklist

Require an idempotency key on lease creation.
Put a unique constraint around the account and key.
Hash tokens and redact them from logs.
Check expiration inside the confirmation transaction.
Commit the outbox event with the lease row.
Keep delivery, verification, and cleanup metrics separate.
Test duplicate requests, delayed messages, and concurrent confirmations.
Keep temp org mail as plain test text only; it is not a safe identifier or an anchor.

Five minutes spent on the state model usually saves hours of debugging later. The useful signal is not merely that an email arrived. It is that the right lease accepted one valid transition, exactly once, with evidence that can be inspected after the test runner has gone away.

Q&A

Should a retry create a new verification email?

Not when it carries the same idempotency key. Return the existing lease and let the delivery layer decide whether a resend is needed. A new user action can use a new key and a new lease.

Can Redis replace PostgreSQL for this state?

Redis can help with short-lived coordination, but the durable account state and idempotency result belong in a transactional store. Using both is reasonable when their responsibilities are explicit.

What should an integration test assert?

Assert the API state, message ownership, token expiry, duplicate-request response, and final database transition. The inbox is evidence in the flow, not the source of truth.

Idempotent Email Verification for REST APIs

kevindev — Wed, 21 Oct 2026 05:22:56 +0000

Email verification is often implemented as a single request: create a user, send a message, and wait for a click. That model breaks down when the client times out after the server has already accepted the request. A retry can create a second token, send a second message, or attach the wrong result to the user.

The fix is to make verification intent idempotent. The API should treat repeated requests as a lookup for the same operation, while PostgreSQL enforces the uniqueness that application code alone can miss.

This matters in both production authentication flows and automated tests that use a free throwaway email or a throwaway email address. A test mailbox is useful only when the API can explain which verification attempt produced the message.

Why verification retries create duplicate work

Suppose a client sends POST /verification-requests and waits six seconds. The server commits the request, but the response is lost. The client sends the same request again without an idempotency key.

The server cannot know whether this is a new request or a retry. It may issue two tokens and deliver two emails. The first retry is mostly harmless; the second one is where things gets confusing. A user clicks the older link, while the database considers the newer token to be current.

Email delivery makes the timing less predictable. A provider can queue messages, a worker can restart, and an inbox can expose messages in a different order than they were created. The REST API needs its own record of intent instead of using inbox arrival time as the source of truth.

For integration tests, a run-scoped email contract is a useful companion to this design. Each run should know which verification request and mailbox it owns.

Define the idempotency contract

Require the client to send an Idempotency-Key header when it starts verification. Scope that key to the authenticated user and operation, then persist the request fingerprint with it.

The endpoint contract can be simple:

The first request creates a verification intent and returns 202 Accepted.
A retry with the same key and the same payload returns the existing intent.
The same key with a different payload returns 409 Conflict.
A new key creates a new intent only when the account is allowed another attempt.

That last rule is important. Idempotency prevents accidental duplicates, but it should not bypass rate limits or account security policy. The API still needs a separate decision about how often a user may request a new message.

Store intent and delivery separately

The verification intent describes what the user asked the system to do. Delivery attempts describe what a worker tried to send. Keeping them separate makes the states less ambiguous:

verification_intent: pending -> sent -> consumed
delivery_attempt:   queued  -> accepted -> delivered
                                  \-> failed

An intent can remain pending while a delivery attempt is retried. It should not be marked verified just because a provider accepted a message. Verification happens only after the user presents a valid, unexpired token.

The database record should include a user ID, an idempotency key, a hash of the request parameters, an expiry time, and a token hash. Do not store the raw token in logs. A test can assert the resulting state without exposing a credential in CI output.

Enforce uniqueness in PostgreSQL

Application checks are not enough when two workers or two HTTP requests run concurrently. Use a unique constraint for the idempotency boundary:

CREATE TABLE verification_intents (
    intent_id uuid PRIMARY KEY,
    user_id uuid NOT NULL,
    idempotency_key text NOT NULL,
    request_hash text NOT NULL,
    status text NOT NULL CHECK (status IN ('pending', 'sent', 'consumed', 'expired')),
    token_hash text NOT NULL,
    expires_at timestamptz NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE (user_id, idempotency_key)
);

On conflict, fetch the existing row and compare request_hash. If the hash differs, return 409; if it matches, return the existing intent. The transaction should not send the email itself. Commit the intent first, then let an outbox worker handle delivery.

This separation also supports operational controls. Deployment workflows can use email failure budgets in deployment workflows to decide when provider failures should stop a rollout rather than making every API request wait for the provider.

Return useful states from the REST API

The client needs a stable status resource instead of guessing from a button spinner:

{
  "intent_id": "3d1d0fb8-0b6a-4b91-ae49-7a3559e0bf2e",
  "status": "sent",
  "expires_at": "2026-10-21T06:00:00Z"
}

Keep provider details out of the public response. A sent status means the delivery workflow accepted the intent, not that the user has read the message. An expired status should be terminal for that intent, while a new request may create another intent if policy allows it.

The API response are easier to debug when each state has one meaning. In local notes, someone might search for temp gamil com or tempail mail; those phrases can appear as plain text, but they should never be used as identifiers or routing logic.

Test the failure paths

The most valuable tests are not the happy-path click. Test a lost response followed by an identical retry, a reused key with a changed email, concurrent requests, an expired token, and a delivery worker that fails after the intent commits.

For an automated test, assert the intent ID and state, then inspect a message matched to that intent. The test does not need to knows the provider's internal timing. It only needs evidence that the right message belongs to the right request.

A useful checklist is:

Require and persist an idempotency key.
Hash request parameters and reject changed retries.
Enforce uniqueness in PostgreSQL.
Commit intent before attempting delivery.
Hash tokens and redact them from logs.
Make expiry and resend policy explicit.
Correlate test messages with an intent ID or run ID.

Idempotent verification turns a fragile email side effect into a recoverable workflow. The provider may still be delayed, and a worker may still fail, but a retry will have a known meaning. That is the boundary an authentication service needs to stay correct under ordinary network failures.

Model Test Email as a Lease in a REST API

kevindev — Tue, 20 Oct 2026 23:22:51 +0000

Email verification tests often fail for a reason that is not really email. A test creates an account, requests a verification message, waits for an inbox, and then asserts that a link arrived. If the inbox is shared or its lifetime is undefined, the test has no reliable answer to a simple question: does this message belong to this run?

I treat a test inbox as a leased resource. The lease has an owner, an expiration time, and a state. That small model makes a REST API easier to retry and gives PostgreSQL enough information to reject stale or competing work. It also keeps temporary disposable mail in its proper place: a controlled fixture for a test environment, not a substitute for an application's identity model.

Why an inbox should have a lease

A mailbox address by itself is not a test fixture. It is only a location. Without ownership and expiry, several jobs can read the same verification email, or a new job can consume a message left by an older one.

The usual workaround is to add a longer sleep. That can hide the race for a while, but it does not identify the message or prevent a different job from reading it. A lease creates a boundary around the resource:

lease_id identifies one reservation.
run_id connects the reservation to the test execution.
address is the mailbox location, ideally generated for this run.
status moves through active, released, or expired.
expires_at tells readers when the reservation is no longer valid.

The boundary matters most when a CI worker is interrupted. The lease can expire without requiring a cleanup process to run perfectly. That is a more dependable contract than assuming every job reaches its finalizer.

Separate verification intent from mailbox ownership

The verification request and the mailbox lease should be related, but they should not be the same row. A verification intent answers, “which account needs a token?” A lease answers, “which test run may inspect this inbox?”

This separation also makes the API states clearer. The signup endpoint may return 202 Accepted after creating an intent. A worker sends the message. A test reader later records evidence that a matching message was observed. The explicit email states in signup flows are useful here because the UI and the test can distinguish pending, verified, expired, and failed instead of treating every non-success response as the same thing.

Do not put the verification token in a log line just to make the test easier to debug. Store a correlation ID and a hash of the expected message attributes. You can then prove that the subject, recipient, and request ID matched without making credentials or live links searchable in CI logs.

Implement the lease with PostgreSQL

A minimal schema can look like this:

CREATE TABLE email_test_leases (
    lease_id uuid PRIMARY KEY,
    run_id text NOT NULL,
    address text NOT NULL,
    status text NOT NULL CHECK (status IN ('active', 'released', 'expired')),
    expires_at timestamptz NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX email_test_leases_active_idx
    ON email_test_leases (address, expires_at)
    WHERE status = 'active';

When allocating an address, use a transaction and lock the candidate row before changing its status. The allocation query should verify expires_at > now() and the caller's run_id. If the row is expired, mark it expired before reusing the address. That ordering is important; otherwise a slow reader may still look like the current owner.

The API that creates the lease should accept an idempotency key. A retry with the same key returns the original lease instead of creating a second reservation. This is where a REST API and the database cooperate: the endpoint owns the contract, while PostgreSQL enforces uniqueness and locking.

For larger suites, keep the lease table small by deleting old rows asynchronously. Do not delete active rows as part of routine cleanup. A cleanup task should first select only leases with expires_at < now() and then update them conditionally with status = 'active'. The condition prevents cleanup from releasing a lease that was renewed between selection and update.

Make REST API retries boring

Every operation in the flow should have a stable idempotency key: allocate, request verification, and record observation. A timeout after the server commits is then recoverable. The client repeats the request, and the server returns the existing result.

The response should expose state, not implementation detail. For example:

{
  "lease_id": "6f7b3d2c-2d2d-4f91-9e77-6bd7d5d0a4bf",
  "state": "active",
  "expires_at": "2026-10-21T07:00:00Z"
}

A client must still handle 410 Gone after expiry. Retrying forever is not resilience; it is noise. The caller should create a new fixture and attach it to a new test attempt, while keeping the old lease ID in the failure record.

The same principle applies to reusable workflows for email API checks: make the setup and evidence steps repeatable, but do not silently reuse state from a previous run.

Use the inbox as evidence, not a timing oracle

Polling should query for evidence that matches the current run: lease ID when supported, otherwise a correlation value in the recipient alias, subject, or message header. A message that merely arrived recently is not enough.

For short-lived integration tests, a temp mail so inbox can provide that controlled boundary. Keep the provider call behind a small adapter so the application test does not depend on provider-specific polling details. In one test note, a developer might type temp mailid or tepm mail com while searching for a fixture; those phrases should never become production identifiers or query semantics.

When the provider cannot return a stable message ID, record the observation time, a normalized subject, and a digest of the relevant headers. The test can then explain why it accepted a message. It may sound slightly extra, but it save hours when a provider delivers messages out of order.

Operational checklist

Give every test run a unique run_id and every mailbox a lease_id.
Enforce one active lease per address with a partial index or equivalent constraint.
Use idempotency keys for allocation and verification requests.
Reject expired leases before reading or releasing them.
Match messages to run-specific evidence, not arrival time alone.
Redact tokens, full addresses, and provider credentials from logs.
Record the last provider message ID and polling error for diagnosis.
Release leases on success, but rely on expiry for interrupted jobs.

This design turns email from an unpredictable external wait into a small state machine. The provider can still be slow, and a worker can still crash, but the API response, database row, and test evidence retain the same meaning after a retry.

Replay-Safe Email Verification Receipts

kevindev — Tue, 20 Oct 2026 17:23:01 +0000

Email verification looks like a short request: create a token, send a message, and return success. The difficult case starts when the provider accepts the message but the network timeout reaches your service first. The worker cannot know whether it is safe to retry, and the user may receive two links.

I prefer treating the delivery result as a replay-safe receipt. The application records one logical verification, gives it a stable delivery ID, and lets a worker update that record with provider evidence. A retry can then repeat the operation without creating a second verification intent.

This is a backend boundary, not just an email feature. It keeps a REST API predictable, makes PostgreSQL state useful during incidents, and gives operators something better than “the request timed out.”

The timeout that creates two verification emails

The first implementation usually look simple:

Insert a verification token.
Call the mail provider.
Mark the token as delivered.

If step 2 times out, the caller may retry the API request. A second token or outbox row is created, even though the first provider call might have succeeded. The result is confusing for users and hard to diagnose from logs.

The fix is to separate intent from attempt. A verification intent says which account is being verified and when the token expires. A delivery attempt says which worker tried to send it, with what idempotency key, and what the provider returned. Those records can be related without being the same thing.

What a delivery receipt should represent

A receipt is not proof that the user clicked the link. It is a durable statement about the delivery boundary:

delivery_id identifies one logical message.
idempotency_key identifies the provider operation.
status distinguishes pending, accepted, failed, and unknown.
provider_message_id stores external evidence when available.
attempt_count, last_error, and next_attempt_at explain retry decisions.
expires_at prevents an old token from being sent after it is useless.

The unknown status is important. A timeout is not always a failure. Marking it as failed and immediately sending again can produce duplicates; marking it accepted without evidence can hide a real outage. A bounded retry policy can resolve unknown outcomes while preserving the original delivery ID.

The receipt should also carry a correlation ID, but not the token or the full email address in ordinary logs. A tempail mail address appearing in a debug line may look harmless, yet retained logs often have a wider audience than the test inbox.

Use PostgreSQL to make replay safe

Create one outbox row per logical verification and enforce that rule in the database:

CREATE UNIQUE INDEX one_active_verification_delivery
ON email_outbox (verification_id)
WHERE status IN ('pending', 'sending', 'accepted', 'unknown');

For the request path, use an idempotency key and a unique constraint scoped to the account or client. If the same request arrives again, return the existing verification response. If the payload differs, return a conflict instead of silently changing the recipient.

Workers can claim pending rows without waiting behind one another:

WITH next_delivery AS (
  SELECT id
  FROM email_outbox
  WHERE status IN ('pending', 'unknown')
    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 20
)
UPDATE email_outbox AS e
SET status = 'sending',
    lease_owner = $1,
    lease_until = now() + interval '90 seconds',
    attempt_count = attempt_count + 1
FROM next_delivery
WHERE e.id = next_delivery.id
RETURNING e.*;

Commit the claim before making the network call. When the response arrives, update by both id and lease_owner. A worker whose lease expired must not mark a row accepted after another worker has reclaimed it. This condition matter more than the exact queue product.

For transient failures, use backoff and a ceiling. For permanent failures, record the provider category and stop retrying. A clean failure record make an incident searchable without replaying the whole request.

Keep the REST API contract stable

The API should expose the state that a client can act on, not internal provider details. For example:

{
  "verification_id": "ver_123",
  "delivery_status": "accepted",
  "expires_at": "2026-10-21T01:00:00Z",
  "retryable": false
}

When delivery is unknown, the client can show that the message is being checked and poll a status endpoint. It should not create another verification just because the original HTTP request had a timeout. Teams often does the opposite because the retry path is easier to add than the state model.

For controlled staging checks, a tempmailso inbox can isolate test traffic from real customer mail, but it does not replace idempotency or provider-side evidence. The useful contract remains in your database.

Test the receipt, not only the inbox

End-to-end tests should simulate the ambiguous cases: provider accepts then times out, worker crashes after claiming, lease expires during a slow send, and the same API request arrives twice. Assert the number of logical deliveries as well as the visible message.

A fixture factory for email tests can make those scenarios repeatable across test cases. At the deployment layer, keep the same evidence mindset as a deploy receipt that explains a CI result: record what happened, which run owned it, and what should happen next.

Do not assert only that an inbox eventually contains a message. Assert that the message belongs to the expected delivery_id, that a late worker cannot overwrite a newer state, and that retry exhaustion produces an actionable error. The test is more useful when it can explain why a delivery was accepted or retried.

Operational checklist

Before shipping this flow, verify:

One unique delivery exists for each logical verification.
Repeated API requests return the same result for the same idempotency key.
Worker claims use short transactions and SKIP LOCKED.
Result updates require a current lease owner.
Unknown provider outcomes have bounded retries and alerts.
Expired tokens cannot be sent by an old worker.
Logs contain correlation IDs instead of tokens or raw message bodies.

The main design decision is to make uncertainty a stored state. Once the delivery receipt is durable, retries become controlled replays instead of guesses, and a provider timeout becomes a case the system can explain.