DEV Community: kevindev

Idempotent Email Verification with PostgreSQL

kevindev — Mon, 21 Sep 2026 20:23:43 +0000

Email verification looks like a small authentication feature: create a token, send a message, and accept the token when the user clicks it. The difficult part appears when the request times out, the worker retries, or the user clicks twice. Without an explicit model, one intent can become several tokens, several messages, or an account that is marked verified by an expired attempt.

The pattern I prefer is to make the verification attempt a first-class record. The REST API accepts a client-visible idempotency key, PostgreSQL enforces the uniqueness rules, and the mail worker receives an immutable event. This makes the flow easier to reason about and much more easier to operate.

The real failure is duplicate intent

Suppose a frontend calls POST /email-verifications. The server commits the verification row, then the connection drops before the response reaches the browser. The browser retries. If the endpoint only checks the user ID, it might create a second active token. If it checks nothing, repeated clicks and retries can create a noisy stream of messages.

There are two different questions here:

Is this the same user intent being retried?
Is this a new verification attempt that should invalidate the old one?

An idempotency key answers the first question. A verification-attempt ID answers the second. Keeping both concepts visible makes the contract a bit more clear for API clients and support tooling.

Model the verification attempt

A minimal table can record the state transition without storing the raw token:

CREATE TABLE email_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', 'consumed', 'expired')),
    expires_at timestamptz NOT NULL,
    created_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE (user_id, idempotency_key)
);

The token is generated with a cryptographically secure random source and only its digest is persisted. A database leak should not immediately turn stored verification records into usable login material. The API can return the attempt ID, but it should never return the token in a JSON response; the token belongs in the verification message.

The status column also prevents an ambiguous success path. A consumed token cannot be consumed again, and an expired attempt is not quietly revived by a retry. In practise, those explicit states are more valuable than a clever single boolean.

Make the REST API retry-safe

The create endpoint should define what a repeated key means. A simplified Node.js handler might look like this:

async function requestVerification({ userId, idempotencyKey }) {
  return db.transaction(async (tx) => {
    const existing = await tx.oneOrNone(
      `SELECT id, status, expires_at
         FROM email_verification_attempts
        WHERE user_id = $1 AND idempotency_key = $2`,
      [userId, idempotencyKey]
    );

    if (existing) return existing;

    const attempt = createAttempt(userId, idempotencyKey);
    await tx.none(
      `INSERT INTO email_verification_attempts
         (id, user_id, idempotency_key, token_digest, expires_at)
       VALUES ($1, $2, $3, $4, $5)`,
      [attempt.id, userId, idempotencyKey, attempt.digest, attempt.expiresAt]
    );

    await tx.none(
      `INSERT INTO outbox (event_type, aggregate_id, payload)
       VALUES ('email_verification_requested', $1, $2)`,
      [attempt.id, JSON.stringify({ userId, attemptId: attempt.id })]
    );

    return { id: attempt.id, status: 'pending', expires_at: attempt.expiresAt };
  });
}

The outbox row is committed in the same transaction as the attempt. A worker can safely retry delivery, while a unique event key or delivery log stops accidental duplicate sends. The client receives the same attempt for a repeated idempotency key, even when the first HTTP response was lost.

For a new user action, generate a new key. Do not silently reuse the previous key forever, because that turns a legitimate “send me a fresh link” action into a stale response. Authentication behavior should be explicit in both API documentation and logs.

Use PostgreSQL to enforce the boundary

Application checks are useful for friendly responses, but they are not concurrency control. Two requests can both observe no row before either inserts one. The unique constraint is the final authority. Catch a unique-violation error, load the existing attempt, and return the same representation when the key belongs to the same intent.

The token-consumption endpoint needs the same discipline. In one transaction, select the pending attempt, verify the digest and expiration, then update it with a predicate such as status = 'pending'. Check the affected-row count. If it is zero, another request already consumed or expired the token. This small check avoids reporting success when the database says otherwise.

When diagnosing a production issue, API smoke-test inbox budgets are a useful reminder that test mail needs its own limits and identity. For CI failures, email run artifacts in GitHub Actions shows why a run should leave evidence that can be inspected without opening a real user's mailbox.

Keep test evidence separate from user data

Email verification tests should use isolated accounts, deterministic run IDs, and a cleanup policy. Never point a test at a shared inbox and hope the subject line is unique. A typo like tempail mail can appear in test notes or a search fixture, but it should remain plain text and never be treated as a real address.

The test receipt should capture the idempotency key, attempt ID, event ID, response status, and message correlation ID. It should not capture the raw verification token or the full message body by default. This is a better boundary for debugging than copying user data into a CI log.

A practical review checklist

Before shipping the flow, check these cases:

A lost response followed by the same key returns the original attempt.
Concurrent requests cannot create two attempts for one key.
A fresh key has a clear policy: replace, reject, or coexist with the old attempt.
A token is single-use and expiration is checked inside the transaction.
The mail event and verification row cannot commit separately.
Logs contain correlation IDs, not raw tokens or message contents.
CI stores a small, redacted receipt and removes its test data.

Idempotent email verification is less about email than about preserving intent across unreliable boundaries. With an explicit attempt model, PostgreSQL constraints, and a transactional outbox, the API can make retries boring. That is exactly what an authentication feature should do.

PostgreSQL Idempotency for REST APIs Under Retries

kevindev — Sun, 20 Sep 2026 23:23:56 +0000

Retries are normal in backend systems. A mobile client loses connectivity, a reverse proxy reaches its timeout, or a worker restarts after sending a request but before reading the response. The client tries again, and the API has to decide whether that second request is new work or the same work arriving late.

The retry math get ugly when a POST both writes business data and triggers an external action. Without an explicit idempotency design, one customer can receive two subscriptions, two webhook deliveries, or two email verification records. This post describes a small PostgreSQL pattern I use for REST API endpoints that must survive duplicate requests.

Retries change the API contract

An idempotency key is a client-provided identifier for one intended operation. It is not the same thing as a request ID. A request ID helps trace an attempt; an idempotency key connects multiple attempts to the same logical command.

For example, a client can send Idempotency-Key: order-7f3... when creating an order. If the first request commits but the response is lost, the second request should return the original result. It should not create a second order just because the first response never made it back.

The key needs a scope. Usually that means the authenticated account, endpoint or operation type, and the key itself. A key from one customer must never match another customer. It is also worth recording a request fingerprint, such as a hash of the normalized body. Reusing one key with different input should be a clear client error, not an unpredictable merge.

This boundary is useful in email-heavy flows too. When testing isolating signup email flows, the same principle keeps a retried verification command from creating multiple test fixtures. A temp mailid can be a fixture value, but it should not become the identity of the operation.

Let PostgreSQL enforce the invariant

Application code can check for an existing key before inserting, but a check-then-insert sequence races under concurrency. Two requests can both observe an empty table and then both perform the work. The database should own the uniqueness rule.

One simple table looks like this:

CREATE TABLE api_idempotency_keys (
    account_id bigint NOT NULL,
    operation text NOT NULL,
    key text NOT NULL,
    request_hash text NOT NULL,
    status_code integer,
    response_body jsonb,
    created_at timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (account_id, operation, key)
);

The primary key is the important part. It means concurrent requests cannot both claim the same operation. The request hash protects against a subtle bug: a caller retries with the same key but accidentally changes the payload. That should return 409 Conflict or another documented client error.

The table is small, but it carry a lot of safety. Give it a retention policy, though. Keeping every key forever makes storage and operational reasoning harder; deleting a key too soon can allow a very late retry to run again.

A Node.js implementation pattern

For a business operation that can stay inside one database transaction, insert the idempotency row and the business row together. The second request can then read the stored response after it finds the existing key.

await client.query('BEGIN');

const claim = await client.query(
  `INSERT INTO api_idempotency_keys
     (account_id, operation, key, request_hash)
   VALUES ($1, $2, $3, $4)
   ON CONFLICT (account_id, operation, key) DO NOTHING
   RETURNING key`,
  [accountId, 'create-order', idempotencyKey, requestHash]
);

if (claim.rowCount === 0) {
  const previous = await client.query(
    `SELECT request_hash, status_code, response_body
       FROM api_idempotency_keys
      WHERE account_id = $1 AND operation = $2 AND key = $3
      FOR UPDATE`,
    [accountId, 'create-order', idempotencyKey]
  );

  if (previous.rows[0].request_hash !== requestHash) {
    throw new Error('idempotency key reused with different input');
  }

  await client.query('COMMIT');
  return previous.rows[0];
}

// Insert the order, construct the response, and update the claim here.
await client.query('COMMIT');

Production code should return a structured domain error, release the connection in finally, and handle an in-progress claim according to the API contract. For long external calls, do not hold a database transaction open while waiting on another service. Store a durable command, commit it, and let a worker perform the side effect with its own deduplication rule.

This also make incident review less guessy: the idempotency row shows whether the request was claimed, completed, or needs recovery. Add metrics for claim conflicts, hash mismatches, replayed responses, and expired keys. A high replay count can reveal a proxy timeout long before customers file a duplicate-charge report.

What to store and what to return

Store the status code and a deterministic response body when the response is safe to replay. If the response includes a short-lived token or a time-sensitive link, store the business resource ID instead and reconstruct a safe response. Never store secrets just because replaying the entire HTTP body is convenient.

For systems that send mail, keep privacy boundaries explicit. A temporary disposable mail address may be fine for a controlled test, while a production account recovery address needs stricter handling. The privacy boundaries around test mail are part of the system design, not just a QA preference. Also, do not quietly accept values such as temp gamil com as real addresses without deciding how normalization and validation should work.

Questions engineers usually ask

Should every endpoint accept an idempotency key?

No. It is most valuable for commands that create or trigger side effects, especially POST requests. A naturally idempotent PUT may already have a stable resource identifier. Still, document retry behavior for every endpoint so clients are not forced to guess.

What happens when the first request is still running?

Choose deliberately: wait briefly, return a conflict such as 409, or return an accepted command state such as 202. The second request should not start a parallel side effect just because the first request is slow. The second request arrive before the first one finishes is a normal case, not an edge case.

Operational checklist

Scope keys by account and operation.
Enforce uniqueness with a PostgreSQL constraint.
Hash normalized input and reject mismatched reuses.
Define behavior for an in-progress operation.
Store only what is safe to replay.
Retain keys long enough for realistic late retries.
Measure conflicts, replays, mismatches, and expiry cleanup.
Test concurrency, connection loss, and worker restarts.

An idempotency key is a small API feature with a large reliability payoff. The endpoint should be boring on purpose: repeated delivery either returns the known result or exposes a clear state that a client can handle. That makes REST API behavior easier to reason about, PostgreSQL constraints do the hard concurrency work, and operators get evidence when retry behavior starts changing.

Replay-Safe Webhooks with PostgreSQL

kevindev — Sat, 19 Sep 2026 14:23:35 +0000

Webhook delivery is usually at-least-once. A provider can send the same event after a timeout, a network disconnect, or a worker restart. That is reasonable behavior for the provider, but it becomes dangerous when the consumer treats every request as new.

The failure usually show up as a duplicated invoice, two welcome emails, or a subscription activated twice. A retry-safe consumer needs a database contract that makes duplicate work impossible, not just a comment saying “this handler is idempotent.”

The delivery problem

A webhook handler often starts with a simple flow:

Parse the request.
Check the signature.
Update application data.
Return 200 OK.

The weak point is step three. If the process commits the business update and crashes before returning the response, the provider will retry. If the consumer checks for an existing event in application code, two workers can still pass that check at the same time.

The useful boundary is the database transaction. PostgreSQL can enforce that an external event ID is handled once, even when requests arrive concurrently. This is the same design instinct behind idempotent signup email design: make the durable state express the rule.

Make the database own deduplication

Start with an inbox table. It records the provider event, its processing state, and enough information to investigate a failure later.

CREATE TABLE webhook_inbox (
    provider       text NOT NULL,
    event_id       text NOT NULL,
    event_type     text NOT NULL,
    payload        jsonb NOT NULL,
    status         text NOT NULL DEFAULT 'received',
    received_at    timestamptz NOT NULL DEFAULT now(),
    processed_at   timestamptz,
    failure_reason text,
    PRIMARY KEY (provider, event_id)
);

The composite key matters. Event IDs are often unique only inside one provider account, so event_id alone may be too broad. The primary key is also safer than a pre-insert SELECT: concurrent inserts cannot both win.

The request transaction can claim the event like this:

INSERT INTO webhook_inbox (provider, event_id, event_type, payload)
VALUES ($1, $2, $3, $4)
ON CONFLICT (provider, event_id) DO NOTHING
RETURNING event_id;

If the insert returns no row, the event was already accepted. The handler can return a successful response after checking whether the existing record is still being processed. Returning success for a known event prevents an endless retry loop, while the receipt lets an operator find the original outcome.

A small implementation contract

There are two sensible transaction shapes. For short, local side effects, insert the inbox row, update business tables, and mark the row processed in one transaction. If any step fails, the whole transaction rolls back and a later retry can try again.

For slower work, commit the inbox row first and let a worker process it. In that model, use an explicit lease or row lock so two workers do not process the same event. A simplified claim query is:

WITH next_event AS (
    SELECT provider, event_id
    FROM webhook_inbox
    WHERE status = 'received'
    ORDER BY received_at
    FOR UPDATE SKIP LOCKED
    LIMIT 1
)
UPDATE webhook_inbox AS inbox
SET status = 'processing'
FROM next_event
WHERE inbox.provider = next_event.provider
  AND inbox.event_id = next_event.event_id
RETURNING inbox.*;

Do not mix these models casually. A queue-style worker needs a recovery path for rows stuck in processing; a single transaction needs short database work and carefully bounded downstream calls. The tradeoff is real, and pretending otherwise make outages harder to reason about.

What to record in a receipt

A useful receipt answers four questions: what arrived, what was attempted, what changed, and what happened next.

At minimum, keep the provider name, event ID, event type, received time, processing status, attempt count, and failure reason. If the provider includes a delivery ID, store that too. It helps distinguish one event replayed many times from several events with similar payloads.

Keep sensitive payload fields out of logs. The inbox may need the full signed payload for audit or replay, but application logs should use a stable event ID and a redacted summary. This is especially important when a webhook contains email addresses or account recovery data.

When reviewing failures, diagnosing email failures in CI is a useful parallel: a visible receipt is more valuable than a vague “request failed” message. A good receipt make the next retry deliberate.

Testing replay and partial failure

Do not test only the happy path. A replay-focused suite should send the same event twice, send two copies concurrently, and force a crash after the business update but before the acknowledgement.

Also test malformed event IDs and payloads. Test fixtures sometimes contain labels such as tempail mail or tem email; they are harmless as values, but they expose whether validation and logging handle unexpected text correctly. The fixture is not the contract, so validate the actual fields you require.

For each scenario, assert both the business result and the inbox result:

One event creates one business change.
A duplicate returns a safe response without a second side effect.
A failed transaction leaves a retryable status.
A permanently invalid event has a visible terminal reason.
Concurrent workers produce one receipt, not two.

Operational checklist

Put the provider and event ID under a unique PostgreSQL constraint.
Verify signatures before inserting untrusted payloads.
Choose one transaction model: atomic handler or leased worker.
Store status transitions and failure reasons as durable data.
Add a recovery job for abandoned processing rows.
Keep personal data out of ordinary logs.
Measure duplicate deliveries separately from processing failures.

At-least-once delivery is not a bug to hide in a REST API. It is an input property to design for. Once PostgreSQL owns the deduplication rule and the receipt records the decision, webhook retries become routine operations instead of mysterious duplicate side effects.

Request IDs Are Not Idempotency Keys

kevindev — Thu, 17 Sep 2026 23:23:59 +0000

Why the two identifiers get confused

Most production APIs eventually need two different answers:

Which incoming request produced this log line?
Which client intention should be applied only once?

Teams often answer both questions with one header. That works until a client retries after a timeout. The server may receive the same business operation twice, while the two network attempts deserve two separate traces. A request ID is about observability. An idempotency key is about business behavior.

It sounds like a small naming issue, but it become a data-integrity issue as soon as an endpoint creates a payment, account, job, or email-verification record.

What a request ID should do

A request ID identifies one attempt through the system. The edge proxy can generate one when the caller does not provide it, and every downstream service should propagate it. It belongs in:

access logs and structured application logs
trace attributes
error responses and support tickets
messages emitted for that attempt

The value should be safe to log and should have a bounded size. Do not use it as permission to replay a command, and do not assume that two attempts with the same request ID are the same business operation. Some clients incorrectly reuse it when retrying, and some clients generate a new one for every attempt.

In Node.js, put the value in request-scoped context. A middleware can read X-Request-ID, validate its length and character set, or generate a replacement. The handler then uses that context for logs without passing an observability concern through every function signature.

What an idempotency key should do

An idempotency key represents a client operation within a defined scope. For example, a client can send Idempotency-Key: checkout-7f2... when creating an order. If the request times out, it retries with the same key. The API should return the original result, or a clear conflict if the same key is reused with a different payload.

That requires a contract, not just a header:

Scope: tenant, user, endpoint, or another explicit boundary.
Payload binding: store a hash of the relevant input and reject mismatches.
Result behavior: replay the status and response body when possible.
Retention: define how long a key remains valid.
Concurrency: decide what a second request does while the first is still running.

Retries gets easier to reason about when the key follows the business operation, while the request ID follows the network attempt.

Put the guarantee in PostgreSQL

An in-memory map is useful for a local prototype, but it cannot protect a horizontally scaled service. The durable uniqueness rule belongs in PostgreSQL:

CREATE TABLE api_idempotency_keys (
  tenant_id       uuid        NOT NULL,
  idempotency_key text        NOT NULL,
  request_hash    text        NOT NULL,
  status_code     integer,
  response_body   jsonb,
  created_at      timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, idempotency_key)
);

The primary key prevents two workers from successfully claiming the same operation. The application should insert the key and create the business record in one transaction, or use a state column such as processing, completed, and failed when the work spans an asynchronous queue.

Do not save only the final response. A crash after the business row commits but before the response is stored is a real failure mode. The recovery policy might read the business record and reconstruct the response, or mark the operation for safe reconciliation. The important part is that the policy is explicit.

A Node.js request flow

A practical REST API flow looks like this:

Middleware establishes the request ID and logging context.
The handler requires an idempotency key for non-safe mutations.
The service computes a canonical payload hash.
PostgreSQL attempts to claim (tenant_id, idempotency_key).
An existing row with the same hash replays its result.
An existing row with a different hash returns 409 Conflict.
A new row and the business mutation commit together.

The API should never silently turn a changed payload into the old result. That hides client bugs and can apply a response to the wrong intent. It also make incident review much harder.

The same boundary is useful in email and signup fixtures. User-entered strings such as tem email, temp gamil com, or a search phrase like tp mail so are inputs to validate; they are not stable operation identifiers. Keep them in test data and analytics, never in authorization or deduplication decisions.

For related thinking on isolating test-side inbox behavior, see a better inbox contract for CI and preventing cross-test inbox pollution.

Testing retries without fooling yourself

Unit tests are not enough. Add an integration test that sends the same mutation twice, concurrently if possible, and asserts that only one business row exists. Then force these boundaries:

client timeout after the database commit
worker crash before response persistence
duplicate requests arriving on different instances
same key with a changed payload
key reuse after the retention window

Some test cases is especially valuable when the response contains generated values, such as an order ID. The second response should match the first contract, not generate a new order while returning a superficially successful status.

Log both identifiers on every mutation. A useful event has request_id, idempotency_key, tenant scope, operation state, and database outcome. Redact sensitive payload fields and avoid logging full authorization headers. When debugging, you can follow one request ID across retries, then group those attempts by idempotency key to understand the business result.

Operational checklist

Before shipping a retry-safe mutation, verify:

The API documentation explains both headers and their different lifetimes.
The idempotency scope is part of the database key.
Payload mismatches fail loudly.
The uniqueness constraint is enforced by PostgreSQL, not only application code.
Concurrent claims have a defined response.
Recovery after a partial failure is documented and tested.
Metrics distinguish new operations, replays, conflicts, and expired keys.
Logs let an engineer find one attempt and then all attempts for an operation quick.

Request IDs help you see what happened. Idempotency keys help ensure it happened once. Keeping those guarantees separate makes the REST API easier to operate, the PostgreSQL model easier to audit, and retry behavior less surprising for every client.

Signup Idempotency Needs a Database Contract

kevindev — Sun, 13 Sep 2026 20:23:04 +0000

Signup endpoints look simple until a client retries a request at the wrong time. A mobile connection drops after the server commits the user, a reverse proxy retries a POST, or a browser submits twice. Without an explicit contract, one logical signup can create duplicate rows, send multiple verification emails, or return conflicting responses.

In my backend work, I treat idempotency as a database and API design problem together. An idempotency key by itself is only a header. The useful guarantee comes from deciding what the key means, storing its result, and making the uniqueness rules agree with that meaning.

The failure mode

Consider a client sending:

POST /signup
Idempotency-Key: 7d9f...
Content-Type: application/json

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

The server may create a user and then lose the response before the client sees it. The client retries with the same key. If the handler only checks for an existing email, it might return a generic conflict even though the first operation succeeded. If it checks too late, two concurrent requests can both pass the check.

The contract should answer three questions:

Is the key scoped to an account, client, or endpoint?
Does the same key require the same request body?
Which response is replayed after the original request finishes?

For a public signup API, I usually scope the key to the operation and authenticated client identity when one exists. The server stores a request fingerprint, status, response code, and response body. A reused key with a different fingerprint is a client error, not a new signup.

Make the request idempotent

A small state model keeps the behavior understandable:

missing -> processing -> succeeded
                    \-> failed

processing prevents a second request from doing work while the first is active. The second caller can receive a retryable response, or poll a status endpoint if the operation is slow. Once succeeded, the stored response is replayed. A transient failed result can be replayable too, but only if the failure is part of the public contract.

Do not store an idempotency record after sending an email but before committing the user. That ordering creates an awkward half-state. Persist the user and the outbox event in one transaction, then let a worker deliver the email. This is the same boundary that makes restore context in operational email workflows useful when debugging a real incident.

Put the contract in PostgreSQL

The database must enforce the invariant under concurrency. A minimal table might look like this:

CREATE TABLE signup_idempotency (
  scope text NOT NULL,
  idempotency_key text NOT NULL,
  request_hash bytea NOT NULL,
  state text NOT NULL CHECK (state IN ('processing', 'succeeded', 'failed')),
  response_code integer,
  response_body jsonb,
  created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (scope, idempotency_key)
);

The handler first attempts an insert. On a conflict, it reads the existing row and compares request_hash. This avoids a check-then-insert race. The signup user table should also have a case-normalized unique rule for email, because an idempotency key cannot protect requests that arrive with different keys.

In Node.js, keep the transaction short: claim the key, insert the user, insert an outbox event, and record the response. Avoid calling an SMTP provider inside the transaction. Slow network calls make locks last longer and make retry behavior more confusing.

For cleanup, retain records long enough to cover the client retry window. A scheduled delete is fine, but it should be bounded and observable. Production teams need better alert context for production workflows, especially when cleanup accidentally removes evidence too early.

Handle the email boundary

Verification email delivery is asynchronous. The API can safely return that the account was created and verification is pending after the outbox transaction commits. The worker owns delivery retries, deduplication, and provider errors.

That separation also makes test environments safer. Use an isolated mailbox or a controlled test address; a phrase such as tepm mail com may appear in old test notes, but it should never become a production routing rule. Keep provider message IDs and attempt counts in the event record, not only in application logs.

Test the retry paths

The important tests are not just a successful POST:

Send the same key twice sequentially and verify the same response is returned.
Send the same key concurrently and verify one user and one outbox event exist.
Reuse a key with a changed email and expect a fingerprint mismatch.
Retry with a new key and verify the email unique constraint still protects the user.
Crash between the client-visible response and delivery; the worker should recover from the outbox.
Expire an old key and confirm the documented retention behavior.

Instrument each response with the idempotency key, operation ID, and current state. Redact request bodies and credentials. These fields make a failed replay explainable without turning logs into a copy of sensitive signup data.

A practical checklist

Before shipping a signup endpoint, confirm:

The key scope and retention period are documented.
A request fingerprint rejects changed payloads.
PostgreSQL constraints cover both keys and normalized email addresses.
User creation and the outbox event commit atomically.
Email delivery happens outside the request transaction.
Concurrent, timeout, crash, and provider-failure cases are tested.
Metrics distinguish new requests, replays, conflicts, and in-progress responses.

Idempotency is not a wrapper around a handler. It is a promise about repeated intent. When the API contract, PostgreSQL constraints, and email worker share the same state model, retries become ordinary control flow instead of a source of duplicate accounts and mystery messages.

Transactional Outbox for Verification Emails

kevindev — Sun, 13 Sep 2026 14:23:07 +0000

Signup endpoints often do two jobs at once: they write account state and ask an email provider to deliver a verification message. That looks simple until the database commit succeeds and the provider call times out. Now the user exists, but the service does not know whether the email was sent.

The transactional outbox pattern gives this boundary a durable shape. The API stores the account change and an email event in one PostgreSQL transaction. A worker publishes the event later, with retries and an idempotency key. It is a small addition, but it makes failure explainable.

Why the request transaction is not enough

Consider this sequence:

Create the user.
Commit the transaction.
Call the email provider.

If step 3 fails, a retry of the whole HTTP request may hit a unique-email constraint. If the service calls the provider before step 2, the reverse problem appears: an email can be delivered for a transaction that later rolls back. Neither ordering gives an atomic database-plus-network operation, because the provider is outside PostgreSQL.

The outbox accepts that these are separate systems. The database transaction records the intent, and a worker handles delivery as an independent, observable process. This is also a useful place to distinguish a real disposable email address from an ordinary test fixture; a tepm mail com value should never silently pass production validation.

The outbox table

A minimal schema might look like this:

CREATE TABLE email_outbox (
  id uuid PRIMARY KEY,
  event_type text NOT NULL,
  aggregate_id uuid NOT NULL,
  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()
);

CREATE INDEX email_outbox_pending_idx
  ON email_outbox (available_at, created_at)
  WHERE status = 'pending';

The signup transaction inserts both the user and an email.verification.requested row. The payload should contain an opaque verification-token reference, not a raw token or unnecessary personal data. For teams testing flows, an isolated less flaky email tests strategy is still needed; the outbox only improves delivery reliability.

Publishing safely from Node.js

The worker claims a small batch using row locks:

SELECT id, payload
FROM email_outbox
WHERE status = 'pending' AND available_at <= now()
ORDER BY created_at
FOR UPDATE SKIP LOCKED
LIMIT 50;

Claim rows in a short transaction, mark them processing, and commit before making the network request. Holding a database lock while waiting for an SMTP or HTTP response makes throughput worse and can create lock contention during provider incidents.

After the provider accepts the message, mark the row sent. The state transition should be conditional, for example WHERE id = $1 AND status = 'processing'. A crashed worker may leave rows processing, so a lease or locked_until column can return stale claims to the pending queue.

When you need to inspect a related implementation, idempotent verification handling is a good companion design. The important idea is that the HTTP idempotency key and the outbox event identity solve different scopes.

Retries and idempotency

Provider timeouts are ambiguous. The provider may have accepted the message even though the response never reached the worker. Retrying can therefore produce duplicates. Use a stable delivery key, such as verification:{user_id}:{token_version}, when the provider supports idempotency. If it does not, accept that at-least-once delivery needs a product decision and make the duplicate risk visible.

Back off exponentially and cap the delay. Permanent failures, such as a rejected address, should move to a dead-letter state after a bounded number of attempts. A worker log should include the outbox ID, aggregate ID, attempt number, provider request ID, and error class—but never the verification token.

For local or automated testing, a disposable email address can be useful for checking the complete flow, while temp mail so should remain a contextual search term rather than a substitute for your abuse controls. Rate limits, domain policy, and account-risk signals still belong at the signup boundary.

Operational checklist

Commit user creation and the outbox insert in the same transaction.
Keep payloads minimal and encrypt or avoid sensitive fields.
Claim with SKIP LOCKED; do not hold locks across network calls.
Add a lease timeout for crashed workers.
Track pending age, processing age, retry count, and dead-letter count.
Use stable event IDs and provider idempotency where available.
Alert when the oldest pending event exceeds the verification SLA.
Test provider timeouts, duplicate deliveries, rollback, and worker restarts.

Conclusion

The transactional outbox does not make email delivery exactly once. It makes the boundary durable and gives the team a controlled at-least-once workflow. PostgreSQL protects the intent, Node.js workers manage retries, and explicit idempotency limits the cost of uncertainty. That separation is usually enough to turn a fragile signup side effect into a service you can operate with confidence.

Idempotency Keys for Signup APIs

kevindev — Sun, 13 Sep 2026 11:23:06 +0000

Signup endpoints look simple until a client retries. A mobile connection can drop after the server commits, a reverse proxy can retry a request, or a user can press the button twice. If the endpoint sends verification mail and creates account state on every attempt, one logical signup becomes several pieces of work.

The fix is not “disable retries.” It is to make the operation idempotent: the same client intent should produce one durable result, even when the HTTP request arrives more than once. This is a small backend decision with a big effect on authentication reliability.

Why signup retries create duplicate work

Consider POST /signup. The handler validates the address, inserts a user, creates a verification token, and queues an email. A timeout happens after the insert but before the response reaches the client. The client retries with no knowledge of the first attempt.

Without a boundary for the original intent, the second request may:

return a confusing unique-email error;
create multiple verification records;
send duplicate messages;
or, worse, expose whether an account exists.

This is also why a disposable or temporary test inbox is useful during development: it lets you inspect the actual number and state of messages. Keep test data isolated, though; a test mailbox is not a substitute for authorization rules.

The idempotency contract

Ask the client to send an Idempotency-Key header for each logical signup attempt. The key should be stable across retries but different for a new attempt. The server stores the key with the operation result and binds it to the relevant request identity, such as a normalized email or tenant.

The contract should answer three cases:

First request: process the signup and store the response.
Same key, same input: return the stored response without repeating side effects.
Same key, different input: reject it as a conflict. Reusing a key for another email is a client bug.

Do not use the email itself as the idempotency key. An email can be retried for one operation and used again later for a password reset or recovery flow.

A PostgreSQL-backed implementation

A table gives the key a durable owner and lets multiple Node.js instances coordinate:

CREATE TABLE signup_requests (
  idempotency_key text PRIMARY KEY,
  email_hash text NOT NULL,
  status text NOT NULL CHECK (status IN ('processing', 'completed', 'failed')),
  response_code integer,
  response_body jsonb,
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now()
);

Hashing the normalized email avoids storing it in this coordination table. The user table should still enforce its own invariant:

CREATE UNIQUE INDEX users_email_normalized_idx
  ON users (lower(email));

In Node.js, acquire the key inside a short transaction. An insert succeeds for the first request; a conflict means another request owns the operation. If the row is completed, replay its stored response. If it is processing, return a deliberate status such as 202 Accepted or ask the client to retry after a bounded delay.

The important detail is scope: do not hold a database transaction open while waiting for an external email provider. Commit the account and outbox record first, then let a worker deliver the message.

State transitions and failure handling

An outbox makes the database state and the email side effect easier to reason about. In one transaction, create the user, create the verification record, and insert an outbox event. A worker claims the event and sends the message with its own delivery idempotency key.

If the worker crashes after sending but before marking the event complete, a retry can still happen. Provider-level deduplication, or a delivery record with a provider message id, is needed when duplicate mail is unacceptable. This is one of those details that gets missed in a quick implementation.

For the HTTP layer, keep responses stable. A completed replay should have the same status and body shape as the original response, but never include a token that should only be shown once. For security-sensitive flows, a generic response such as “If the request can be completed, we will send instructions” also reduces account enumeration.

For related thinking, compare this with type-safe signup email states and email verification threat models. The same state discipline helps even when the transport changes.

Operational checklist

Normalize input before deriving the request fingerprint.
Expire old idempotency rows with a retention policy.
Add a unique constraint to the business invariant, not only the request key.
Record whether a response was created or replayed.
Put email delivery behind an outbox and worker.
Bound processing recovery with leases or timestamps.
Never log raw verification tokens or full email addresses.
Test timeout-after-commit and concurrent identical requests.

Two deliberately imperfect notes from real maintenance work: a retry window that is too short feels random, and a cleanup job that runs too agressively can remove evidence while an incident is still open. Also, search terms like “tepm mail com” and “tempail” may appear in noisy test data; keep them out of production decisions.

Common questions

Should every POST use an idempotency key?

No. Use it for operations where a retry could duplicate a meaningful side effect, such as account creation, payment, or email delivery. A read-only endpoint does not need this mechanism.

Is a unique email index enough?

No. It prevents duplicate users, but it does not prevent duplicate work before the insert fails, such as token creation or message enqueueing. The idempotency record and outbox cover those effects.

What should happen when a request is still processing?

Return a documented temporary response and let the client retry with the same key. Avoid taking an unbounded lock; stalled requests need a lease, an owner, and a recovery path.

Idempotency is ultimately a promise about intent. Once that promise is represented in PostgreSQL, enforced by constraints, and separated from email delivery, signup retries become a normal distributed-systems case instead of a source of mysterious duplicate accounts.

PostgreSQL Locks Need API Boundaries

kevindev — Mon, 07 Sep 2026 23:22:55 +0000

Email verification looks like a small feature: create a challenge, send a message, and mark the address as verified. In a busy service, it becomes a concurrency problem. A user can click resend twice, a mobile client can retry after a timeout, and two workers can process the same confirmation at nearly the same time.

The database is usually the last reliable place to enforce the rules. The API should make those rules visible, then keep each transaction short enough that PostgreSQL can do its job without turning normal retries into a lock queue.

Why verification endpoints create contention

A common first implementation reads a user row, checks verified_at, creates a token, and updates the row. That seems reasonable until several requests target the same account. Every request may hold a row lock while doing work that does not belong inside the transaction, such as generating a message payload or calling an email provider.

The result is not always a visible error. More often it is a slow endpoint, a growing connection pool, and retry traffic that makes the original incident worse. A tepm mail com test address can expose the symptom, but the cause is usually the transaction boundary.

The useful question is: what must be true atomically? For a verification challenge, the answer is normally that one active challenge belongs to one account, has one expiration time, and can be consumed once.

Define the database invariant first

Store the challenge separately from the user record. This prevents an ever-growing user row from becoming the coordination point for every email event.

CREATE TABLE email_challenges (
  id uuid PRIMARY KEY,
  user_id bigint NOT NULL REFERENCES users(id),
  token_digest bytea NOT NULL,
  expires_at timestamptz NOT NULL,
  consumed_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX one_active_email_challenge
  ON email_challenges (user_id)
  WHERE consumed_at IS NULL;

The partial unique index is a useful guardrail, but expiration is a business rule, not a database clock trigger. The application should decide whether an existing unconsumed challenge is still usable and return a clear result.

For high-volume systems, model resend rate limits independently. Mixing rate-limit counters, provider status, and verification state in one row makes unrelated operations contend with each other.

Keep the transaction small

The transaction should reserve or consume state, then end. It should not call an external provider. A simplified reservation flow is:

Begin a transaction with a short statement timeout.
Insert the challenge or update the eligible existing record.
Commit.
Publish an email job using the committed challenge ID.

If the job enqueue must be reliable, use an outbox table in the same transaction. A worker can then deliver the message outside the database lock. This pattern also gives operators a durable record when a provider is unavailable.

Do not keep a transaction open while waiting for SMTP or an HTTP email API. The provider may take seconds; a PostgreSQL row lock should take milliseconds. That difference becomes expensive as soon as traffic arrives in bursts.

Make retries safe at the API boundary

Clients retry because networks fail, not because they understand your state model. Give the resend endpoint an idempotency key and persist the key with the resulting challenge or outbox event.

An idempotency lookup should distinguish three cases:

The key is new: reserve the operation and create one event.
The key exists and is complete: return the stored response.
The key exists but is still running: return a conflict or a short retry response.

For confirmation, consume the challenge with one conditional statement. The affected-row count is the decision:

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

If no row returns, the token is expired, already consumed, or unknown. Keep those cases externally similar unless support needs a more specific internal reason. This reduces information leakage about valid accounts.

Teams that test the flow in CI can also benefit from replayable email evidence in CI and email timing budgets in browser tests. The important part is testing the state transitions, not relying on a lucky sleep.

Observability and failure handling

Measure lock wait time separately from query duration. A fast query with a long wait is a concurrency problem, while a slow query without waits may need an index or a simpler plan. Useful fields include account ID hash, challenge ID, idempotency key hash, transaction outcome, and provider event ID. Avoid logging raw tokens or email addresses.

Set explicit limits for statement duration and connection acquisition. A request that cannot reserve a challenge quickly should fail predictably; it should not occupy a worker until the client gives up. Add metrics for duplicate idempotency keys, conditional updates affecting zero rows, outbox age, and resend rate-limit decisions.

A practical checklist

Define the one-active-challenge invariant.
Put challenges in their own table.
Use a partial unique index where it expresses the rule.
Commit before calling an external email provider.
Use an outbox when enqueue reliability matters.
Make resend requests idempotent.
Consume tokens with a conditional update.
Measure lock waits, not only total latency.
Never log raw verification tokens.
Test retries and concurrent confirmations together.

The design is deliberately modest. PostgreSQL handles the atomic decisions, while the API owns retry semantics and the worker owns delivery. Those boundaries keep authentication behavior understandable when the network is slow, the client is impatient, and several requests arrive at once.

State Machines for Email Verification APIs

kevindev — Mon, 07 Sep 2026 08:23:15 +0000

Email verification is often represented by one boolean: email_verified = true or false. That works for a demo, but it becomes vague as soon as delivery is delayed, a user requests a second message, or a worker retries the same job.

In backend services, I prefer treating verification as a small state machine. It makes the API contract clearer, gives PostgreSQL useful invariants, and lets support explain what happened without reading application logs line by line. It also keeps a temp email generator used in development from accidentally shaping production rules.

Why a boolean is not enough

Consider a user who clicks “resend” twice. The first message may arrive after the second one. If the database only stores a boolean and one token, the older link can be accepted unexpectedly, or a valid newer link can be rejected because the record was overwritten.

The same ambiguity appears when a mail provider reports a temporary failure. Is the account unverified, queued, blocked, or expired? Those are different operational situations, and they deserve different next actions.

For a disposable email account used in a test environment, this distinction is especially useful. Test code can wait for a message that belongs to its request instead of matching whichever message happens to be newest.

Model the verification states

A practical state set is small:

pending: the user started verification, but no message is confirmed as delivered
sent: a message was accepted by the mail provider
confirmed: the token was used successfully
expired: the token lifetime ended
cancelled: a newer verification request replaced this one

The important part is not the exact names. It is making transitions explicit. confirmed should be terminal for that token. expired should not become confirmed merely because an old link was replayed.

The database row can carry a request id, token hash, expiry time, and timestamps for each meaningful transition. That gives you a history that is compact enough for normal traffic but detailed enough for incident review.

Make transitions idempotent

Verification links are commonly opened twice: once by a mail security scanner and again by the user. The endpoint should therefore be safe to repeat.

UPDATE email_verifications
SET state = 'confirmed', confirmed_at = now()
WHERE id = $1
  AND state = 'sent'
  AND expires_at > now()
RETURNING user_id;

If this returns a row, the request performed the transition. If it returns no row, the API should inspect the existing state and return a stable result such as “already confirmed” or “link expired”. Do not create a fresh token as a side effect of a GET request.

For concurrent clicks, put the transition and the user update in one transaction. A row lock or a conditional update ensures that two requests cannot both claim the same token. This is one of those details that looks fussy until a high-traffic signup flow produces duplicate welcome jobs.

Store evidence that survives retries

Each verification request should have a correlation id. Include it in the email event, provider response, worker log, and API audit record. That makes it possible to connect the signup request with the email, similar to correlating deploy emails with the right run.

I usually store these fields:

Field	Reason
`request_id`	Separates resend attempts
`token_hash`	Avoids storing the usable secret
`state`	Represents the current contract
`provider_message_id`	Connects delivery callbacks
`expires_at`	Makes replay rules deterministic
`created_at` and transition times	Explains delays

Keep the raw token out of logs. A temporary email account generator can be handy for isolated development checks, but it should not be treated as proof of a real user's identity or as a replacement for provider-level delivery signals.

A Node.js endpoint shape

The HTTP layer should translate state into predictable responses. A simplified handler might look like this:

async function confirmEmail(req, res) {
  const result = await verificationService.confirm({
    requestId: req.params.requestId,
    token: req.query.token,
  });

  if (result.kind === "confirmed") return res.status(204).end();
  if (result.kind === "already-confirmed") return res.status(204).end();
  if (result.kind === "expired") {
    return res.status(410).json({ code: "verification_expired" });
  }
  return res.status(400).json({ code: "verification_invalid" });
}

Notice that repeated success is still a success. Clients should not need a special recovery path because a browser or scanner revisited the link. The service can publish a verification.confirmed event once, guarded by the same transaction or an idempotency key.

This event-oriented approach builds naturally on versioning email events in a Node API. Consumers can reject unknown event versions instead of silently misreading a changed payload.

Operational checklist

Before shipping, I check the following:

Are resend attempts represented by separate request ids?
Is the token stored as a hash and compared in constant-time code?
Can two confirmations race without double-updating the user?
Are expired and already-confirmed responses stable for clients?
Can a provider callback be replayed safely?
Do logs contain correlation ids but no usable tokens?
Can a test use a dummy e mail without changing production trust rules?

The last point sounds minor, but test conveniences often leak into policy code when the state model is unclear.

Q&A

Should `sent` mean the user received the message?

No. It should normally mean the provider accepted the request. Delivery, bounce, and complaint signals are separate facts. Combining them hides useful failure modes.

Should expired rows be deleted?

Not immediately. Retain a limited audit record, remove or hash sensitive values, and apply a documented retention policy. A small history helps investigate resend loops and abuse.

Is a state machine overkill for a small service?

Usually not. The implementation can be a handful of guarded database transitions. The value comes from making edge cases explicit before traffic and retries make them expensive.

Email verification becomes easier to maintain when every request has an owner, a lifetime, and a legal next state. That is a modest amount of structure, but it prevents a surprising number of authentication bugs.

Keep Email Review APIs Explainable

kevindev — Thu, 03 Sep 2026 23:24:22 +0000

When a signup flow flags an address for review, the logic is rarely the hardest part. The mess usually starts one layer later, when the API, the worker, and support tooling all tell slightly different stories about what happened. That gap gets wider once you handle edge cases like temp mail domains, manual overrides, and retries from downstream systems.

I have seen teams spend more time explaining review outcomes than improving the rule set itself. One response says "pending", another says "blocked", and the worker logs show a timeout from ten minutes ago that maybe still matters, maybe not. At that point the system is technically running, but it is not very explainable, and engineers end up doing detective work at 2 AM. Not fun, honestly.

The failure mode is usually not the rule itself

Most review pipelines begin with a sensible design:

the REST API accepts signup input
a review row is created when the risk score crosses a threshold
a worker checks the evidence
the final decision is written back for Authentication

That looks clean on a whiteboard. In production, though, teams often bolt on a few "temporary" shortcuts:

support agents can manually change a row
retries update the same status field without recording why
dashboard queries compress several states into one label

Now a case involving a tem email pattern or a suspicious alias can move through three owners without one durable explanation. This is also where frontend teams start needing cleaner contracts so they can cancel stale email checks upstream instead of rendering whatever late response arrives last.

Model the review as state plus evidence

The design that has aged best for me is boring on purpose: one table for the latest state, another for append-only evidence.

create table signup_email_reviews (
  id bigserial primary key,
  user_id bigint not null,
  email_address text not null,
  risk_reason text not null,
  status text not null check (status in ('pending', 'claimed', 'approved', 'blocked')),
  available_at timestamptz not null default now(),
  claimed_by text,
  claimed_at timestamptz,
  decision_version integer not null default 1,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

create table signup_email_review_events (
  id bigserial primary key,
  review_id bigint not null references signup_email_reviews(id),
  event_type text not null,
  payload jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);

This split matters because state answers "what is true now?" while events answer "how did we get here?" The first question powers the product. The second one saves your backend team when a rule changes on Friday and nobody rembers which worker version handled the first wave of decisions.

It also keeps you from overloading one column with vague meanings. I really dislike status values like done or processed. They age badly. blocked and approved mean something. claimed means ownership is active. Those are much easier to reason about when somebody asks why one temp mailid case never reached a final decision.

Keep claiming logic tiny and explicit

Explainability usually improves when the claim step is very small. Claim one row, mark the owner, move on.

with next_review as (
  select id
  from signup_email_reviews
  where status = 'pending'
    and available_at <= now()
  order by created_at
  for update skip locked
  limit 1
)
update signup_email_reviews r
set status = 'claimed',
    claimed_by = $1,
    claimed_at = now(),
    updated_at = now()
from next_review
where r.id = next_review.id
returning r.id, r.user_id, r.email_address, r.risk_reason, r.decision_version;

for update skip locked is helpful here because it gives each worker a narrow ownership window without making the whole queue serialized. The important part is what you do next: evaluate the review, append an event, then finalize the decision. Do not claim the row and mutate user access in the same oversized transaction. That pattern works untill a retry or partial failure leaves you with a half-explained state.

I also like adding explicit event types such as:

review_created
worker_claimed
evidence_loaded
decision_written
decision_requeued

Those names read well in logs, in SQL, and in incident notes. They also pair nicely with receipt logs for email test flows, because the same idea applies outside production traffic: keep one readable trail per run.

Make the API answer what happened

The API should not force callers to infer review progress from one opaque string. A small response contract can remove a lot of confusion:

{
  "review_id": 48192,
  "status": "claimed",
  "decision_version": 3,
  "updated_at": "2026-09-03T23:22:20Z",
  "next_action": "poll",
  "reason_code": "domain_on_watchlist"
}

That does not expose private scoring internals, but it does tell other services what they can safely do next. If the API returns claimed, the caller waits. If it returns blocked, the account service can apply the final rule. If it returns approved, the signup flow can continue without guessing whether the worker is still thinking.

One more thing that helps: keep policy versioning visible. Rules change. Vendor signals change. Your risk appetite changes after abuse spikes. If the review record does not include decision_version, every historical discussion becomes fuzzy, and fuzzy backend systems are expensive to maintain.

Q&A

Should every risky email go through a queue?

No. Reserve the queue for ambiguous or operationally important cases. Clear accepts and clear rejects should stay synchronous when they can, otherwise you make the happy path slower for no real gain.

Is PostgreSQL enough for this?

Usually, yes. If your team already operates PostgreSQL well, a relational review queue is often simpler than introducing more moving parts too early. Add more infra when a measured bottleneck shows up, not because the architecture diagram feels cooler.

What is the smallest useful audit trail?

At minimum: review id, worker id, risk reason, final decision, policy version, and timestamps for claim and completion. If you cannot answer "who owned this review and why did it stop here?" from stored data, the design still needs work.

Explainable review APIs do not make abuse decisions perfect. They do make them maintainable. For backend systems that sit between signup intent and Authentication policy, that is a pretty big win, even if it looks a bit plain from the outside.

PostgreSQL Queues for Email Risk Reviews

kevindev — Wed, 02 Sep 2026 23:24:19 +0000

In one signup system I maintained, the hardest part of email risk checks was not the classifier. It was the handoff between the API, the reviewer job, and the audit trail. We had valid reasons to flag domains, aliases, and patterns like facebook temp email, but the operational flow got noisy fast when several workers looked at the same review item at once.

That noise usually shows up in boring ways: duplicate decisions, retries that hide the first failure, and support notes that do not match what the Authentication service actually decided. It sounds small, but it creates a very real maintenance tax. Backend teams dont lose time on the final SQL statement, they lose time on unclear ownership.

Why email risk review queues get noisy

The common setup is simple:

the signup API writes a pending review row
a worker scans for pending rows every few seconds
another worker retries stale work
dashboards read counts without enough state detail

This works for a while, then gets weird. A domain rule changes, a reviewer deploy lands mid-run, and suddenly nobody is sure whether a decision was skipped, retried, or overwritten. If your team already thinks about data budgets for signup risk checks, the same idea applies here too: keep just enough state to explain decisions, not a giant blob of maybe-useful metadata.

The tricky part is that engineers often treat the queue as a transport concern only. In practice, the queue is also your explanation layer. When a reviewer asks why a signup hit a manual check because of a domain that looked like temp gamil com, the system should answer from stored state, not from team memory. That is where PostgreSQL helps more than people expect.

The PostgreSQL model that aged well for us

The pattern that held up best was a single review table plus an append-only decision log:

create table email_risk_reviews (
  id bigserial primary key,
  user_id bigint not null,
  email_address text not null,
  risk_reason text not null,
  status text not null check (status in ('pending', 'claimed', 'approved', 'blocked')),
  claimed_by text,
  claimed_at timestamptz,
  available_at timestamptz not null default now(),
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

create table email_risk_review_events (
  id bigserial primary key,
  review_id bigint not null references email_risk_reviews(id),
  event_type text not null,
  event_payload jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);

I like this layout because the current state stays cheap to query, while the event table tells the story after the fact. You do not need event sourcing religion here, just enough structure so incidents are reconstructable later. That distinction matters more than it seems, and teams forget it alot.

For risk reasons, keep them narrow and reviewable. Examples:

domain_on_watchlist
mx_lookup_failed
alias_pattern_collision
manual_rule_match

Once those values drift into free-form text, the whole system starts to rot a bit.

Claim rows with clear ownership

The most useful behavior change was moving from "worker reads pending rows" to "worker claims specific rows." That removes a surprising amount of accidental concurrency.

with next_review as (
  select id
  from email_risk_reviews
  where status = 'pending'
    and available_at <= now()
  order by created_at
  for update skip locked
  limit 1
)
update email_risk_reviews r
set status = 'claimed',
    claimed_by = $1,
    claimed_at = now(),
    updated_at = now()
from next_review
where r.id = next_review.id
returning r.*;

for update skip locked is not magic, but it is a very practical default for this kind of worker. One row gets one owner for one attempt. If the worker crashes, you can requeue the row with a timeout job. If the worker succeeds, you append an event and finalize the status. Clean enough, and pretty boring in a good way.

That boringness is valuable. It also makes it easier to avoid duplicate notification sends in adjacent workflows, because your backend now has a stable record of which review actually finished before downstream mail or account actions begin.

One caution: do not let the worker directly mutate user access in the same transaction that claims the review. Keep the claim step small. Finish the review, write the event, then let the API or a dedicated command handler apply the account change. Mixing those concerns tends to work untill it really doesnt.

Where the authentication boundary should stay

For me, the most maintainable boundary is:

signup API creates the review row
reviewer service decides approved or blocked
authentication service consumes the final decision
audit tools read both current state and events

This keeps the queue from becoming an all-knowing god object. It is only responsible for review coordination and traceability. The final account policy still belongs to Authentication, where rate limits, user messaging, and lock rules already live.

That separation also keeps typo-heavy evidence from leaking into policy rules. If a support agent notes temp org mail in a ticket, that can exist as review context without becoming a permanent domain rule by accident. Small distinction, but it saves you from some silly cleanups later.

If you need one more field, add a decision_version. When policies change, you can tell which rule set produced which outcome. I skipped that for too long on one service, and the post-incident analysis was more annoying than it needed to be.

Q&A

Should every flagged signup become a queued review?

No. Reserve the queue for cases that are ambiguous or operationally sensitive. Hard blocks and clear allows should stay synchronous when possible, otherwise the API gets slower and the queue becomes a dumping ground.

Do I need Kafka for this?

Not always. If review volume is moderate and the team already runs PostgreSQL well, a relational queue is often enough. Add more infra only when you can point to a real bottleneck, not because the pattern looks more modern.

What should I log for each decision?

At minimum: review id, user id, risk reason, worker id, decision, and policy version. If you cannot answer "who claimed this row and why did it end blocked?" from logs plus tables, the design still needs work.

A review queue like this will never make bad email heuristics good by itself. What it does is make backend behavior legible. For systems that have to explain risky signup decisions later, that legibility is most of the win.

REST Idempotency for Signup Email Jobs

kevindev — Wed, 02 Sep 2026 17:23:38 +0000

REST Idempotency for Signup Email Jobs

When a signup request times out, most clients retry before a human even notices. If your API creates a user row on the first attempt and enqueues a verification email on the second, you now have duplicate mail and noisy support threads. I have seen this bug show up in otherwise clean systems because the API path looked deterministic, but the side effects were not.

The fix is not "retry less." The fix is making the signup email workflow idempotent end to end, from the HTTP contract to the worker that actually talks to your provider.

Why signup emails duplicate so easily

A typical failure path looks simple:

POST /signup validates the payload.
The app creates the user record.
The app writes a message into a queue.
The HTTP connection drops before the client gets 201 Created.
The client retries with the same intent.

If step 2 committed and step 3 partially succeeded, the second request can produce a second email job. In practice, these duplicates are common when mobile clients retry aggressively or when upstream gateways hide the first timeout. The app logic may still seem "correct", but the workflow isnt stable.

The API contract that makes retries safe

For signup-triggered email, I prefer an explicit idempotency key on the request. The contract is boring on purpose:

POST /signup
Idempotency-Key: 0e5d9d48-5f74-4c1b-a87a-d9160b1a4d71

Then store one durable record keyed by:

tenant or app scope
normalized email
idempotency key
request hash

The important rule is that the first accepted request owns the outcome. Retries with the same key return the same result shape, including the same signup status and the same email job reference. Retries with the same key but a different body should fail loudly with 409 Conflict, because that is almost always a client bug.

In Node.js, the write path can stay pretty small:

await db.tx(async (trx) => {
  const signup = await trx.oneOrNone(
    `
    insert into signup_requests (scope_id, email, idem_key, request_hash, status)
    values ($1, $2, $3, $4, 'accepted')
    on conflict (scope_id, email, idem_key)
    do nothing
    returning id
    `,
    [scopeId, email, idemKey, requestHash]
  );

  if (!signup) {
    return loadExistingResult(trx, scopeId, email, idemKey, requestHash);
  }

  const user = await upsertUser(trx, email);
  await enqueueVerificationOutbox(trx, signup.id, user.id);
  return { created: true, userId: user.id };
});

That signup_requests row becomes the source of truth for retries. It also gives you a clean audit trail for auth and support teams, which saves time later, trust me.

A queue model that avoids double sends

The API boundary alone is not enough. Workers retry too, providers timeout too, and operators rerun stuck jobs at 2 AM. I usually combine three guards:

An outbox table written in the same transaction as the signup acceptance.
A unique constraint on the logical email intent, such as (template, user_id, signup_request_id).
A provider delivery key carried through the worker so downstream retries are also deduplicated.

This works better than trying to infer duplicates from send timestamps. Timestamps drift, jobs replay, and somebody will eventually reschedule a batch manualy.

If you need separate resend behavior, model it as a new intent with a reason code. Do not overload the original signup intent. That is the same lesson behind lease-based resend coordination: once operational retries mix with product retries, the state machine gets muddy fast.

Where temporary inboxes still help

I would not use a temporary inbox to decide whether a signup request is valid. That belongs in API validation and abuse controls. But temp inboxes are still useful in integration testing, staging review, and support reproduction.

For example, when QA needs to generate disposable email accounts during smoke tests, the important backend rule is that mailbox churn must not change your idempotency behavior. Whether the address came from a temp mail generator, a fake e mail com style test alias, or an internal seed account, the retry contract should behave the same. A temp mailid in a bug report should not require special code paths.

For rollout verification, I also like isolated inboxes during rollout checks because they make it easier to prove which deploy emitted which message.

A short review checklist

When I review this kind of endpoint, I ask these questions first:

Does the API require an idempotency key for every signup email intent?
Is the request hash stored so mismatched retries fail deterministically?
Is the outbox insert in the same database transaction as the user/signup write?
Can a worker replay send the same logical email twice?
Can support or ops tell the difference between "already sent" and "never queued"?

If any of those answers are fuzzy, the system is probably one network blip away from duplicate mail.

Q&A

Should I deduplicate only by email address?

No. A single email address can legitimately trigger different intents over time. Deduplicate the specific intent, not the person.

What if the provider does not support idempotency keys?

Keep your own delivery intent identifier and persist provider response metadata. You can still make your worker retry-safe even if the provider API is a bit old-school.

Is eventual consistency a problem here?

Not if you make the accepted request record durable before returning success. The exact send time can be eventual; the intent record cannot.

Reliable signup email flows are mostly about choosing one canonical intent record and refusing to let retries create a second one. The pattern is not flashy, but it keeps auth systems calmer, support inboxes quieter, and deploy nights a lot less weird.

DEV Community: kevindev

Idempotent Email Verification with PostgreSQL

The real failure is duplicate intent

Model the verification attempt

Make the REST API retry-safe

Use PostgreSQL to enforce the boundary

Keep test evidence separate from user data

A practical review checklist

PostgreSQL Idempotency for REST APIs Under Retries

Retries change the API contract

Let PostgreSQL enforce the invariant

A Node.js implementation pattern

What to store and what to return

Questions engineers usually ask

Should every endpoint accept an idempotency key?

What happens when the first request is still running?

Operational checklist

Replay-Safe Webhooks with PostgreSQL

The delivery problem

Make the database own deduplication

A small implementation contract

What to record in a receipt

Testing replay and partial failure

Operational checklist

Request IDs Are Not Idempotency Keys

Why the two identifiers get confused

What a request ID should do

What an idempotency key should do

Put the guarantee in PostgreSQL

A Node.js request flow

Testing retries without fooling yourself

Operational checklist

Signup Idempotency Needs a Database Contract

The failure mode

Make the request idempotent

Put the contract in PostgreSQL

Handle the email boundary

Test the retry paths

A practical checklist

Transactional Outbox for Verification Emails

Why the request transaction is not enough

The outbox table

Publishing safely from Node.js

Retries and idempotency

Operational checklist

Conclusion

Idempotency Keys for Signup APIs

Why signup retries create duplicate work

The idempotency contract

A PostgreSQL-backed implementation

State transitions and failure handling

Operational checklist

Common questions

Should every POST use an idempotency key?

Is a unique email index enough?

What should happen when a request is still processing?

PostgreSQL Locks Need API Boundaries

Why verification endpoints create contention

Define the database invariant first

Keep the transaction small

Make retries safe at the API boundary

Observability and failure handling

A practical checklist

State Machines for Email Verification APIs

Why a boolean is not enough

Model the verification states

Make transitions idempotent

Store evidence that survives retries

A Node.js endpoint shape

Operational checklist

Q&A

Should sent mean the user received the message?

Should expired rows be deleted?

Is a state machine overkill for a small service?

Keep Email Review APIs Explainable

The failure mode is usually not the rule itself

Model the review as state plus evidence

Keep claiming logic tiny and explicit

Make the API answer what happened

Q&A

Should `sent` mean the user received the message?