DEV Community: kevindev

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.

PostgreSQL Audits for Email Change APIs

kevindev — Sat, 29 Aug 2026 17:23:54 +0000

Changing an account email looks like a small feature, but it creates one of the messiest edges in Authentication. You are replacing an identifier, sending a verification link, preserving recovery trails, and making sure retries do not leave support guessing what happened. I keep solving this with a PostgreSQL audit model instead of treating the mailbox as the source of truth.

This matters even more when staging checks involve a facebook temp email or a quick tempmailso inbox to confirm delivery. Those inboxes are useful, but they should validate the last mile only. The system still needs a durable record of which address was requested, who approved it, and whether the token that reached the inbox still matched the latest request. Without that, the backend gets fuzzy fast.

Why email change APIs are riskier than signup

Signup flows are usualy append-only. Email changes are not. You already have a live account, an old verified address, and a new pending address that might never complete verification. If the client retries twice, or a user clicks an old link after requesting a new one, the API can drift into confusing states unless the model is explicit.

The cases I watch most are:

repeated PATCH /account/email calls during slow mobile networks
stale verification links being opened after a newer request
support needing to explain which request actually won
staging notes that mention things like temp gamil com or tempail, which tells me the verification trail is too manual

That last point sounds small, but it often reveals weak observability. If engineers are searching inboxes before they can answer a database question, the design is probly upside down.

The PostgreSQL records I keep for every email change

I prefer a dedicated table for change intents rather than overloading the user row with pending fields only:

create table email_change_requests (
  id uuid primary key,
  user_id uuid not null,
  old_email text not null,
  new_email text not null,
  status text not null,
  token_hash text not null,
  requested_at timestamptz not null default now(),
  expires_at timestamptz not null,
  verified_at timestamptz,
  superseded_by uuid,
  request_key text not null unique
);

request_key is the important guardrail. I generate it from the authenticated user id plus a client operation id. That gives me one durable handle for retries, similar in spirit to immutable retry receipts. If the same request is replayed, PostgreSQL gives me the existing row instead of creating competing email-change attempts.

I also keep the old email on the request row. That looks redundant until a support ticket lands three weeks later and somebody needs to confirm exactly what was replaced.

A REST API flow that survives retries and stale links

The request path is simple on purpose:

await db.tx(async (trx) => {
  const existing = await findByRequestKey(trx, requestKey);
  if (existing) return existing;

  const req = await insertEmailChangeRequest(trx, {
    userId,
    oldEmail: currentEmail,
    newEmail,
    tokenHash,
    requestKey,
    expiresAt: addMinutes(new Date(), 20)
  });

  await enqueueVerificationEmail(trx, req.id);
  return req;
});

On verification, I do not update the user row from the token alone. I first load the request by token hash, confirm it is still pending, confirm superseded_by is null, and only then swap the email in the same transaction that marks the request verified. If a newer request exists, the old link resolves to a clear conflict instead of silently mutating the wrong state.

That is the part many teams skip. They validate expiry, but not freshness. For email changes, freshness matters more than elegance.

How I test the flow without trusting inboxes alone

My test checklist has two layers. First I inspect database truth:

create the email change request through the public REST API
confirm one email_change_requests row exists for the request key
assert older pending rows are marked superseded when a newer request is made
verify the user row changes only after the newest token is consumed

Then I inspect delivery truth through a temporary inbox. A facebook temp email can help when you need to validate content, timing, and whether the right person-facing copy shipped. That is also where tempmailso can be useful in staging. But I do not let the inbox answer backend questions it cannot answer. For template rendering and delivery smoke coverage, I like pairing this with lightweight email template smoke checks.

When teams rely on inboxes alone, they miss two important facts: whether the request was already superseded, and whether a retry reused an existing operation or created a second one. PostgreSQL is better at both answers, and it does not forget what happend.

Q&A

Why not store `pending_email` directly on the user row?

You can for very small apps, but it hides history. Once retries, support, and stale links show up, a request ledger is much easier to reason about.

Should the verification token be unique per request?

Yes. One token per request, one request per request key. That keeps invalidation rules obvious and makes audits less messy.

What about rate limits?

Apply them at the authenticated user boundary and at the destination email boundary. Otherwise attackers can grind through address changes or flood one mailbox with verification messages.

For me, the win is not just security. It is operational clarity. A PostgreSQL request ledger gives the Authentication flow a stable memory, keeps the REST API honest under retries, and turns temporary inboxes into a useful check instead of the only evidence you have.

Canonicalize Auth Emails Before You Rate-Limit

kevindev — Tue, 25 Aug 2026 23:24:05 +0000

I keep seeing Authentication systems rate-limit the wrong thing. The code looks reasonable at first: take the email string from the request, hash it, increment a counter, and decide whether the user can ask for another verification or reset email. The bug shows up later, when Jane.Doe+trial@Example.com and jane.doe@example.com produce different counters, different logs, and a very confusing support trail.

That matters even more when your signup flow already deals with disposable temporary email patterns, temp mail so style test traffic, and a mix of user-entered aliases. If the API does not canonicalize before policy and rate-limit checks, abuse controls get oddly soft while legitimate users still hit rough edges. I have seen teams chase notes with phrases like tamp mail com or temp mailid in incident docs because nobody persisted the normalized form that the system actually reasoned about. It works, until it kind of doesnt.

Why raw email strings create auth bugs

A raw email string is user input, not identity. Case, dots, plus-addressing, Unicode normalization, and domain aliases can all change how the same inbox is represented. Some providers ignore dots, some do not. Some teams strip plus tags globally, which is also wrong. The real backend job is to define a small canonicalization policy per provider class and persist the result that downstream services use.

If you skip that step, four things drift:

resend cooldowns become inconsistent
abuse scoring gets split across aliases
support cannot explain why one request was blocked
test evidence becomes annoyingly fuzzy

This is the same reason I like keeping reproducible email checks around a single normalized artifact. One input form, one decision record, one trail you can review later.

Canonicalize before policy and rate limits

My preference is simple: parse, normalize, classify, then write one receipt row before any async send begins. That receipt should include the original input, the canonical address key, the domain classification, and the policy version used to make the decision.

For example:

type EmailDecisionReceipt = {
  requestId: string;
  rawEmail: string;
  canonicalKey: string;
  providerClass: "generic" | "gmail_like" | "enterprise";
  domainCategory: "standard" | "disposable" | "blocked";
  policyVersion: number;
  resendWindowSeconds: number;
  decision: "allow" | "review" | "deny";
};

The useful trick is that canonicalKey should be the input to both policy lookup and resend throttling. Not the raw address. Not a half-normalized cache key in one service and a different hash in another. One canonical key. Boring, explicit, reviewable.

For disposable temporary email checks, I usually classify the domain separately from the canonical local part. That keeps domain-level controls independent from user-specific resend logic. It also means you can tighten trial-abuse rules without rewriting the whole auth path, which is nice when product wants a fast change by Friday afternoon.

A PostgreSQL receipt shape that stays reviewable

I like a table like this because it keeps write-time evidence close to the send decision:

create table auth_email_receipts (
  id bigserial primary key,
  request_id uuid not null,
  raw_email text not null,
  canonical_key text not null,
  provider_class text not null,
  domain_category text not null,
  policy_version integer not null,
  decision text not null check (decision in ('allow', 'review', 'deny')),
  resend_window_seconds integer not null,
  created_at timestamptz not null default now()
);

create index auth_email_receipts_lookup_idx
  on auth_email_receipts (canonical_key, created_at desc);

This is not meant to be your forever audit lake. It is a working receipt for backend behavior. The benefit is very practical: when retries happen, or a queue delays a send, engineers can still answer which canonical identity the REST API used and which rule set fired. That answer is often missing in systems that only log the raw request body.

If you also publish CI evidence, the same idea behind short CI email summaries helps here too. Keep the receipt terse enough that another engineer can compare runs quickly.

What to return from the REST API

The client does not need all of this detail. It needs stable outcomes. My usual response shape is small on purpose:

{
  "status": "accepted",
  "request_id": "d6f5c4b2-2b36-4b87-8d0d-112233445566",
  "cooldown_seconds": 90,
  "decision_code": "email_verification_scheduled"
}

Then the server-side receipt preserves the backend truth. If a user retries with a different casing or alias, you can still tie the cooldown to the same canonical identity when your policy says that is appropriate. For Authentication APIs, that reduces duplicate sends and weird branchy logic in workers. It also makes Postgres queries much saner, which is not glamorous but is honestly where half the reliability comes from.

One caution: do not over-normalize. Gmail-like dot folding is not universal, and stripping plus tags for enterprise domains can create bad collisions. A small provider-class map is better than a fake universal rule. Overconfidence here causes more mess than slow rollout does.

Small checks that prevent painful regressions

The most useful checks are not huge:

test that raw variants map to one canonical key when your provider rules say they should
test that different enterprise aliases do not collapse by mistake
log the policy version next to the receipt
keep retention short and documented
make the resend query hit canonical_key, not raw_email

I would also add one contract test that proves a disposable temporary email domain still gets classified correctly after a policy update. Teams often validate the deny path and forget the review path, which is where real-world edge cases live a bit more often.

Q&A

Should I canonicalize in the API or in the database?

Usually in the API, then persist the result. PostgreSQL can enforce constraints and help with lookup speed, but the normalization policy is application behavior and should be versioned there.

Do I need a separate receipt row for every resend attempt?

Yes, if you care about debugging. Keep each decision small and timestamped. Trying to mutate one row into the whole story gets messy fast.

Is this worth it for small apps?

If you send verification or reset emails, yes. The table is tiny, the logic is boring, and the payoff arrives the first time support asks why two "same" addresses behaved differently.

Session Proof for Email Change APIs

kevindev — Sun, 23 Aug 2026 23:24:33 +0000

Email change APIs get safer when proof is tied to the session that asked for it, not just to a token floating around later.

Why email change APIs fail in quiet ways

The risky part of an email change flow is rarely the happy path. It is the gap between "user asked to change address" and "backend accepted the new address as trusted". I keep seeing systems that issue a verification token, save a pending email, and call it done. That works until a stolen session, a replayed link, or a retried request lands at the wrong time.

Three failures show up a lot:

The verification link is opened from a different auth state than the one that requested it.
A second change request silently overwrites the first pending email.
Support can see that a change happened, but cannot explain which session actually approved it.

Those bugs are annoying because the API still looks clean from the outside. Internally, though, the trust boundary is mushy. For Authentication work, I want one narrow rule: the proof for changing an address must stay attached to the session context that initiated it, or at least to a re-auth event derived from that context.

Bind proof to the active session

My preferred model is simple. When POST /account/email-change is called, the API creates a pending change record with:

current user id
current session id or re-auth event id
old email
requested new email
hashed verification token
expiry time
state

That extra session binding looks boring, but it removes a lot of guesswork later. If the link comes back with a valid token but the originating session was revoked, stepped up, or replaced by a more recent request, the API can reject the change cleanly. That is the kind of boring failure I like.

In practice, I use a short re-auth window before starting the change. Password prompt, passkey assertion, or MFA step are all fine. The important bit is to persist the proof artifact you actually trust, not just the resulting token. Otherwise the token becomes a tiny passport with very little context, and thats where weird account-takeover stories begin.

A Node.js flow that survives retries

In Node.js, I treat the request flow as a state machine instead of a pair of loose handlers. Roughly:

Require recent re-auth.
Insert a pending_email_change row.
Invalidate older pending rows for the same user.
Send the verification email with an idempotency key.
On link open, verify token hash, session proof, expiry, and row state in one transaction.
Swap the account email and mark the row consumed.

A stripped down service layer might look like this:

async function startEmailChange(db, userId, sessionProofId, nextEmail) {
  await db.tx(async (tx) => {
    await tx.query(
      `update pending_email_change
       set state = 'superseded'
       where user_id = $1 and state = 'pending'`,
      [userId]
    );

    await tx.query(
      `insert into pending_email_change
       (user_id, session_proof_id, next_email, token_hash, state, expires_at)
       values ($1, $2, $3, $4, 'pending', now() + interval '20 minutes')`,
      [userId, sessionProofId, nextEmail, issueTokenHash()]
    );
  });
}

The point is not the exact SQL. The point is that retries should converge on one active intent. If a mobile client resends because the network is flaky, or the browser double-submits, the flow should stay a bit boring. That same idea also helps when you want one email source of truth across frontend and backend validation.

On the callback side, I avoid a "token matches, therefore approve" shortcut. I check whether the stored session proof is still valid for the account and whether the pending row is still the latest one. This is one place where engineers sometimes wave away risk because the token was emailed, but email ownership alone is not always enough for sensitive profile changes.

What to persist for operators

If the flow causes an incident, operators need more than a boolean success flag. I normally persist:

requested_at
verified_at
session_proof_id
superseded_by
failure_reason
request_ip_hash or trusted device marker

That gives support and security teams a usable timeline without turning the system into a surveillance mess. It also makes it easier to answer questions like:

Did the same user request two different addresses?
Was the earlier request still pending when the second one started?
Did verification happen after the re-auth window expired?

I also log a stable reason code for each rejection. "expired", "superseded", "stale_session_proof", and "already_consumed" are much better than a fuzzy "invalid token" bucket. Small detail, big payoff later.

For some teams, statistics help win the argument. Microsoft has repeatedly documented that MFA and stronger sign-in verification drastically reduce account compromise risk, which is why binding sensitive account changes to recent proof is not just security theater (source). Numbers like that should guide the control, but the daily work is still about clean backend state.

Testing without fooling yourself

I do not like tests that only assert "some email arrived". For this flow, the useful cases are:

Two rapid change requests leave only one pending row.
A verified token from the first request fails after the second request supersedes it.
A token with the right hash still fails if the bound session proof is stale.
The audit trail explains every rejection path.

Manual tests with a disposable inbox can still be handy, especially when QA wants to inspect the full email body. I just keep that outside the trust model. If somebody writes tem email in a test plan, fine, but the backend should never depend on inbox tooling to decide whether an account change is legit.

This is also where email retry boundaries in tests matter. If the test runner keeps polling forever, you can miss the fact that your API produced two sends or approved the wrong request. Tight retry windows catch more real bugs, even if they feel a little less comfy.

Q&A

Should the verification link only work in the same browser?

Not always. For many products that would be too strict and kind of annoying. What should stay bound is the proof record, not necessarily the exact browser tab. If you allow cross-device completion, require the callback to reference a recent re-auth artifact that is still valid for that account.

Do I need this for low-risk products?

If users can change the email that controls password resets, invoices, or admin notices, yes probably. It is a compact control with pretty good leverage, and it ages well as the app grows.

What if the user requested the change but lost the session?

Let them restart the flow. That is cleaner than trying to rescue a half-trusted request. Security UX is better when the recovery path is obvious, even when it adds one more click or two.

Session-bound proof turns email change APIs from "token says yes" into "system can explain why yes". For backend teams, that difference is not flashy, but it saves a lot of messy debugging later and makes the whole flow feel more honest.

PostgreSQL Rules for Burner Email Signups

kevindev — Sat, 22 Aug 2026 02:24:10 +0000

Most teams start with a simple email regex and call the signup flow done. That works until abuse, fake trials, and support noise start stacking up. When a burner email address slips through, the real issue is usually not detection alone. It is that the policy lives in three places at once: app code, a vendor dashboard, and somebody's half-remembered runbook.

I prefer to make signup email policy a backend artifact first. Put the rules in PostgreSQL, version them, and let the API return a small set of reviewable outcomes. It sounds a bit boring, but boring systems age better. In auth flows, boring is good even when product wants things fast.

Why signup rules drift over time

Disposable-domain checks often begin as a list in source control. A few weeks later, support asks for exceptions. Marketing wants softer handling for trials. Security wants hard blocks for domains used in credential stuffing. Then another service adds its own copy because it needs a quick decision in middleware. Now the same rule is enforced four differnt ways, and nobody fully trusts the result.

That drift gets worse when the rule engine is hidden behind vague booleans like is_disposable = true. In practice, teams need more nuance:

block known abuse domains
allow but flag low-confidence cases
bypass checks for invited enterprise tenants
expire temporary overrides automatically

I have seen incidents where engineers searched notes for odd phrases like tamp mail com or temp gamil com because they were trying to reconstruct how a previous exception had been tested. The weird phrasing is not the problem, the missing system record is.

Model the policy in PostgreSQL first

My default design is a small rule table plus a decision log. The table tells the API what to do. The log tells humans why the API did it. That second part matters more than teams expect.

create table signup_email_policy (
  id bigserial primary key,
  domain text not null,
  action text not null check (action in ('allow', 'flag', 'block')),
  reason text not null,
  source text not null,
  confidence smallint not null check (confidence between 0 and 100),
  tenant_id uuid,
  starts_at timestamptz not null default now(),
  ends_at timestamptz,
  policy_version integer not null,
  unique (domain, coalesce(tenant_id, '00000000-0000-0000-0000-000000000000'::uuid), policy_version)
);

create index signup_email_policy_active_idx
  on signup_email_policy (domain, starts_at, ends_at);

There are three choices here that save pain later.

First, keep action explicit. Teams argue less about allow, flag, and block than they do about overloaded booleans. Second, store policy_version so incident reviews can answer which ruleset made the decision. Third, allow tenant-scoped exceptions without forking the whole policy model.

For the read path, I usually normalize the domain, query active rules, then choose the highest-confidence match. PostgreSQL is good at this if you keep the query plain:

select domain, action, reason, confidence, policy_version
from signup_email_policy
where domain = $1
  and starts_at <= now()
  and (ends_at is null or ends_at > now())
  and (tenant_id is null or tenant_id = $2)
order by tenant_id desc nulls last, confidence desc, policy_version desc
limit 1;

That does not need to be clever. It needs to be inspectable at 2 PM and at 2 AM. If your signup service also runs test inbox scenarios, the same discipline used in stable email test isolation across workers is useful here too: isolate one run, one decision, one audit trail.

Keep the API response boring and consistent

The API should not leak every internal signal to the client. Return a stable contract, and keep the richer reasoning in server logs or an admin view. A shape like this is enough for most Authentication workflows:

{
  "decision": "flag",
  "code": "signup_email_review_required",
  "policy_version": 12,
  "retryable": false
}

What I try to avoid is returning different status codes for every sub-case. If some burner domains get 422, others get 409, and others get 202, client logic becomes messy for no real gain. In many systems, two patterns are enough:

201 when signup may proceed
202 or 422 when the request needs review or is blocked, depending on your product contract

The point is consistency. Client teams should not need a secret decoder ring. This part is easy to under-value, but it keeps mobile, web, and partner API behavior from drifting apart again.

Add reviewable signals instead of hidden magic

A lot of teams bolt on a third-party reputation feed and stop there. That can help, but I would not let an opaque score become the only source of truth. Store the evaluated domain, matched action, policy version, and request metadata in a decision log with retention that matches your privacy policy.

This is also where privacy review gets easier. If you can show what was stored, why it was stored, and when it expires, review conversations stay shorter and much less fuzzy. The same habit behind privacy review evidence for inbox deletion applies to signup policy logs: write down just enough evidence that another engineer can verify the control later.

My checklist is pretty short, and thats on purpose:

rules live in PostgreSQL, not scattered constants
policy changes are versioned
API returns a small and durable decision set
exceptions expire unless someone renews them
decision logs are queryable by domain and policy version
product and support can tell the difference between flag and block

If you already have rate limiting, device risk, or invite-only onboarding, this model fits beside them without much drama. The burner email address check becomes one signal among several, instead of a giant if-statement that keeps growing sideways.

Questions teams usually ask

Should we block every disposable domain?

Usually no. Some products genuinely need strict blocking, but many do better with a flag path first. It catches risky signups without punishing legitimate evaluation flows too early.

Should the domain list live only in Redis?

I would not do that for the source of truth. Cache hot decisions in Redis if needed, sure, but keep PostgreSQL as the auditable record. Otherwise policy debugging gets annoyingly fuzzy.

What is the most common mistake?

Treating this as only a detection problem. It is also a change-management problem. If you cannot explain which rule fired and when it was added, the system may work, but it wont stay maintainable for long.

Node.js Audit Trails for Email Change Flows

kevindev — Fri, 21 Aug 2026 05:24:45 +0000

Changing a user's email address looks simple until support asks who approved it, which token was active, and whether the old address was warned before the new one went live. In a Node.js backend, that flow gets much easier to maintain when the audit trail is designed first instead of added later.

Why email change flows become hard to explain

Most teams start with one table update and one verification email. Then edge cases pile up:

The user requests a change twice from two devices.
The old address receives a warning after the new address is already verified.
A retry worker sends another token with slightly different expiry data.

At that point the API may still "work", but it becomes hard to explain. For Authentication work, explainability matters a lot. If you cannot reconstruct what happened from database facts, your incident review gets fuzzy real fast.

I now treat email change as a bounded workflow with explicit state. That sounds heavier than a plain users.email = ? update, but in practice it removes a ton of support pain and weird rollback logic.

Model the request as a state machine

I like storing email change requests separately from the user row:

create table email_change_requests (
  id bigserial primary key,
  user_id bigint not null,
  old_email text not null,
  new_email text not null,
  state text not null check (
    state in ('pending', 'verified_new', 'confirmed_old', 'applied', 'expired', 'cancelled')
  ),
  verify_new_token_hash text not null,
  confirm_old_token_hash text,
  requested_at timestamptz not null default now(),
  expires_at timestamptz not null,
  applied_at timestamptz
);

That table gives the flow a home. More importantly, it stops the users table from carrying half-finished identity changes.

My usual rules are:

only one active request per user
verifying the new address does not immediately swap login identity
applying the change requires a final state transition you can audit later

When the state machine is explicit, retries stay boring. A second request can reuse the active record or cancel it deliberately. A stale token can fail cleanly. An operator can inspect one row and know what is still pending, which is pretty nice.

Keep the audit trail append-only

The request row tracks current truth. The audit log should track how truth changed over time.

create table email_change_events (
  id bigserial primary key,
  request_id bigint not null references email_change_requests(id),
  event_type text not null,
  actor_user_id bigint,
  ip_address inet,
  user_agent text,
  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);

Every meaningful step writes an event: request created, new email verified, old email warned, change applied, request expired. I do not mutate old events. I append new ones. That keeps the chain readable, and it avoids the classic "last writer wins" mess where you lose the context that made the current row valid.

This also pairs well with privacy reviews for staging inboxes. The same discipline that makes production events auditable makes test environments less chaotic too. If your notes mention tamp mail com or temp gamil com during manual QA, the important bit is that the backend timeline still reads clearly.

A compact Node.js implementation

The route handler should create intent, not finish identity mutation on the hot path.

async function requestEmailChange(db, userId, nextEmail, context) {
  return db.tx(async (trx) => {
    const active = await findActiveEmailChange(trx, userId);

    if (active) {
      return { status: 202, requestId: active.id };
    }

    const request = await insertEmailChangeRequest(trx, {
      userId,
      oldEmail: context.currentEmail,
      newEmail: nextEmail,
      verifyNewTokenHash: context.verifyTokenHash,
      expiresAt: context.expiresAt,
    });

    await insertEmailChangeEvent(trx, {
      requestId: request.id,
      eventType: "requested",
      actorUserId: userId,
      ipAddress: context.ip,
      userAgent: context.userAgent,
    });

    return { status: 202, requestId: request.id };
  });
}

Then a separate verification handler can move pending -> verified_new, and another command can move verified_new -> applied after your policy checks pass. Keeping those transitions small matters more than clever abstractions, honestly.

One thing I learned the hard way is to avoid rewriting the same token row during retries. It feels efficient, but it makes support logs harder to trust. Append an event, maybe extend expiry under a clear rule, and keep the request identity stable.

Where disposable inboxes actually help

A disposable email account is useful for testing the contract around the flow, not for replacing the contract. I use it to confirm that:

the old email warning is sent once
the new email verification link maps to the right request
expired requests stop producing fresh side effects

For manual checks, the best throwaway email setup is the one that lets you isolate one request from another without sharing a team inbox. That is useful, but it should remain a small test helper beside your database assertions, not the main source of truth.

I also like pairing this with stable onboarding email checks on the frontend side and privacy reviews for staging inboxes when teams are deciding what should reach test mailboxes in the first place.

Q&A

Should the old email always confirm the change?

Not always. For low-risk products, warning-only may be enough. For high-risk accounts, old-email confirmation or a stronger step-up check is often worth it.

Where should expiry live?

In the request record, not just inside the token. That makes cleanup jobs and operator queries much more obvious.

Is this too much for a small app?

Usually no. The schema is small, the state transitions are readable, and the support story gets way better. Even small apps hit enough concurrency and account-recovery weirdness that a clean audit trail pays back quick.

PostgreSQL Leases for Resend Email APIs

kevindev — Thu, 20 Aug 2026 17:24:17 +0000

Resend-email endpoints break when the API, worker, and database disagree about who owns the next send. PostgreSQL leases make that ownership visible and pretty durable.

Why resend endpoints drift out of sync

The bug usually starts with a reasonable shortcut. A POST /auth/resend-verification route checks whether the user is pending, enqueues a job, and returns 202. Later, support sees duplicate messages, stale tokens, or a resend that claims success while nothing was actually deliverd.

What changed? Normally one of these:

The worker timed out after the provider accepted the request.
The client retried on a slow network.
Another node handled the same resend before the first write fully settled.

When send ownership lives only in process memory, you cannot answer a basic backend question: "which attempt currently owns delivery?" That is why I now model resend work as a leased database record, not a loose side effect.

Lease the send in PostgreSQL, not in app memory

A lease is just a short-lived claim on the next delivery attempt. I store resend work in a table where one row represents one email intent. The worker must atomically move the row from pending to leased before it talks to the provider.

That sounds tiny, but it fixes a bunch of messy edge cases:

duplicate sends become far less likely
retries can inspect ownership instead of guessing
operators can see stuck work with one query
API responses stop pretending the mail was already sent

In PostgreSQL, FOR UPDATE SKIP LOCKED is the part that keeps concurrent workers from grabbing the same pending row. It is not magic, but it is very dependable when the rest of the flow stays simple.

A schema that keeps retries boring

I like a table shaped roughly like this:

create table email_delivery_intents (
  id bigserial primary key,
  user_id bigint not null,
  purpose text not null,
  state text not null check (state in ('pending', 'leased', 'sent', 'failed', 'consumed')),
  lease_expires_at timestamptz,
  idempotency_key text not null,
  token_hash text,
  provider_message_id text,
  failure_code text,
  created_at timestamptz not null default now(),
  sent_at timestamptz
);

Then the worker claims work like this:

with next_job as (
  select id
  from email_delivery_intents
  where purpose = 'signup_verification'
    and state = 'pending'
  order by created_at asc
  for update skip locked
  limit 1
)
update email_delivery_intents i
set state = 'leased',
    lease_expires_at = now() + interval '2 minutes'
from next_job
where i.id = next_job.id
returning i.id, i.user_id, i.token_hash, i.idempotency_key;

The key is not the exact SQL. The key is making ownership first-class. If the provider call later fails, I can decide whether to retry the same row, mark it failed, or let the lease expire and recover it. That decision becomes data-driven, which is nice because data ages better than hand-wavy queue logic.

REST API behavior that stays honest

For the API, I avoid saying "email sent" unless a send has actually been recorded. Most resend endpoints should return something closer to "accepted, work is now owned by delivery intent X".

My usual rules are:

Reuse an existing active intent for a short replay window.
Create a new pending intent only when the prior one is consumed or failed.
Never mint a fresh token just because a client got impatent and clicked again.

Here is a compact Node example:

async function requestResend(db, userId) {
  const current = await findActiveIntent(db, userId);

  if (current && ['pending', 'leased', 'sent'].includes(current.state)) {
    return { status: 202, intentId: current.id };
  }

  const created = await createPendingIntent(db, userId);
  return { status: 202, intentId: created.id };
}

This pairs well with an idempotent verification email flow. I also like keeping a small runbook for reclaiming expired leases, the same way frozen plans for automation runs keep cron systems easier to reason about.

One subtle benefit: incident review gets much cleaner. You can ask which resend was pending, which worker leased it, and whether the lease expired before the provider callback arrived. Those are useful backend facts, not vibes.

Where disposable inboxes fit

Disposable inboxes are helpful, but they should verify the contract rather than replace it. When I test resend flows locally, I want proof that one lease produced one effective message, not just proof that some inbox eventually got mail.

A simple test loop looks like this:

create a fresh user
call resend twice under the same auth context
assert only one row is leased or sent
verify one inbox receives one valid link

For that last step, a throwaway inbox from tempmailso can be useful during manual checks. I still keep it as a small part of the story, though. If somebody scribbles tamp mail com in a test note, your resend logic should still be deterministic and auditable.

Q&A

How long should the lease last?

Long enough for one provider attempt plus a small buffer. In most apps, 60 to 180 seconds is enough. If you make it too long, recovery gets slow. If you make it too short, healthy sends may get reclaimed early, which is not ideal tbh.

Should I delete failed intents?

Usually no. Keep them for reconciliation and support analysis, then archive later. Failed rows are often the fastest way to explain weird resend behavior from last night.

Is this overkill for a small app?

Not really. The schema is small, the API rules are clear, and the operator experience is much better. Even modest auth systems get weird concurrency at the worst possible moment, so a boring lease model pays for itself pretty quick.

If your resend endpoint keeps acting random under load, do less in memory and more in PostgreSQL. Once delivery ownership is visible, the whole system gets calmer, and honestly a bit easier to trust.

Version Auth Emails With Attempt Receipts

kevindev — Thu, 13 Aug 2026 14:24:30 +0000

In most auth systems, email delivery looks simpler than it really is. A signup or password reset request enters the REST API, one row changes state, and a worker sends the message later. Then a retry happens, a cooldown rule changes, or the user submits the form twice from two tabs. Suddenly the team is arguing about whether the second email was expected or whether the first receipt is still valid.

What has worked better for me is treating every auth email decision as an immutable attempt with its own receipt. Instead of one mutable email_status field on the user record, the backend writes a new attempt row each time policy is evaluated. That row explains why the message was queued, skipped, or superseded. It sounds small, but it makes production debugging much less fuzzy.

Why auth emails need attempt receipts

One mutable status field collapses too many decisions together:

did the API accept this request?
did cooldown policy suppress it?
did a worker already claim the send?
did a newer verification attempt replace it?

Those questions are related, but they are not the same event. When you store them in one field, retries become hard to reason about. That is extra true when disposable inboxes or abuse heuristics are part of the flow. A support ticket might mention a strange address like fake e mail com, while QA might be checking a temporary disposable mail flow in staging, and the database still only says sent.

I prefer an append-only attempt table because it preserves the sequence. You can see that attempt 17 was skipped for cooldown, attempt 18 was queued after the window expired, and attempt 19 was invalidated because the user changed their address. That history is boring in the best way. It lets the backend answer "what happened?" without guessing from current code.

What goes wrong with one mutable status field

The common shortcut is a user or session row with fields like last_email_sent_at, verification_status, and maybe email_job_id. That works for the first version, but it breaks down when behavior becomes slightly richer.

Here is the pattern I keep seeing:

The first request writes queued.
A second request arrives before the worker finishes.
The API overwrites the same row with suppressed or requeued.
Observability now reflects the latest story, not the full story.

At that point, your team starts reading logs to rebuild state. If logs rotate, or if a worker message shows up late, the explanation gets annoyingly weak. This is also where weird strings like tempail sneak into test traffic and make the investigation feel more messy than it should be.

The better boundary is to make each policy evaluation durable and immutable. Then "current state" can be derived from the newest valid receipt instead of overwritten by it.

A PostgreSQL model for immutable attempts

For PostgreSQL, I like an auth_email_attempts table plus an outbox table keyed by the same receipt id:

create table auth_email_attempts (
  receipt_id uuid primary key,
  user_id bigint not null,
  flow_type text not null,
  email text not null,
  normalized_email text not null,
  attempt_number integer not null,
  decision text not null,
  supersedes_receipt_id uuid,
  policy_snapshot jsonb not null,
  created_at timestamptz not null default now()
);

create unique index auth_email_attempts_active_idx
  on auth_email_attempts (user_id, flow_type, attempt_number);

The important thing is not the exact schema. It is the shape of the evidence:

one immutable receipt per evaluated attempt
one policy snapshot explaining the decision
one clear link to any older receipt it replaced

If you want to know which email is current, query for the newest receipt that was not superseded. If you want to know why a send never happened, inspect the stored decision and snapshot. That beats reconstructing intent from four partially related tables.

Writing receipts inside the REST API transaction

The receipt should be written in the same transaction that decides whether a send may happen. Do not leave policy evaluation to a later worker if you can avoid it. Otherwise the API and worker can drift, and the final record stops matching what the caller was told.

A clean flow looks like this:

Normalize the submitted email and classify the flow.
Load the latest active receipt for that user and flow.
Evaluate cooldown, address policy, and resend rules.
Insert a new receipt row with the decision snapshot.
Insert an outbox row only when the decision is queued.

That sequence gives you stable behavior under retries. If the client resubmits, the API can create a new receipt that says suppressed_cooldown without destroying the earlier queued receipt. If the worker crashes after claiming the outbox row, you still know which receipt it belonged to. It feels a bit more verbose at first, but it pays for itself pretty fast.

I also like combining this with trace-backed inbox debugging because the test can assert the receipt id before it waits on the inbox. And if your team is doing privacy reviews for staging email flows, immutable receipts make retention boundaries easier to discuss, since the schema is already explicit about what evidence you keep.

How receipts improve debugging and testing

This design helps in a few very practical ways.

First, debugging gets narrower. When a user says "I got two verification emails," you can compare two receipts and see whether the backend intentionally issued both or whether one worker retried the same job. That answer is usually visible in one query, which is nice.

Second, API behavior becomes easier to test. A backend test can assert that a resend creates a new receipt with supersedes_receipt_id set, instead of just checking whether some timestamp moved. That is a much stronger contract, and honestly more maintainable.

Third, support and product stop relying on fuzzy timelines. The receipt ids give everyone the same vocabulary. Attempt 42 was queued. Attempt 43 was suppressed. Attempt 44 replaced 42 after the cooldown. Small thing, big clarity.

Q&A

Do I still need an outbox table?

Yes. The receipt explains the decision; the outbox handles delivery work. Keep those concerns separate, even if they share identifiers.

Is this overkill for a small app?

Not really. If your product has signup, reset, or magic-link flows, immutable receipts are one of those small backend habits that age suprisingly well.

Should I keep every receipt forever?

Usually no. Keep them long enough for support, incident review, and trend analysis, then archive or delete based on policy.

Store Email Policy Snapshots With Auth Events

kevindev — Tue, 11 Aug 2026 05:25:25 +0000

In auth systems, email failures are rarely about one missing send() call. The real problem is that the system forgets why it decided to send, suppress, or reroute a message at that moment. Weeks later, support sees a complaint, QA has a screenshot, and the backend only has a boolean like email_sent = true. That field is almost useless.

What has worked better for me is storing a small policy snapshot beside each auth email event. Not just the recipient address, but the normalized address, the rule version, the reason code, and any delivery guard that shaped the decision. In a REST API backed by PostgreSQL, this gives you a clean audit trail without turning the user record into a junk drawer.

Why send flags stop being useful

A plain send flag tells you that some code path ran. It does not tell you:

which normalization rules were active
whether the address was considered risky or disposable
whether resend cooldown logic suppressed the message
whether the provider was skipped because the request already had a valid receipt

That missing context matters when email policy changes over time. Maybe last month you blocked a domain pattern. Maybe you tightened alias handling. Maybe the signup form started rejecting strings that looked like dummy e mail in abuse-heavy traffic. If you only keep the current rule set in code, your historical auth events become weirdly hard to explain.

This is extra important for password reset and verification flows, where a small mismatch can look like an account issue. I like the framing in safer recovery email evidence: keep enough evidence to debug the decision, but not so much that logs become their own privacy problem.

Snapshot the policy, not just the address

The snapshot does not need to be huge. I usually persist a compact JSON object with the fields that explain the decision:

{
  "normalized_email": "sam@example.com",
  "rule_version": "email-policy-2026-08-01",
  "delivery_decision": "allowed",
  "reason_code": "default_allow",
  "cooldown_window_seconds": 900,
  "address_traits": ["plus_alias", "consumer_domain"]
}

The key idea is simple: save the evaluated result, not only the raw input. If you later change canonicalization rules, you can still answer what the system believed at the time. That is often the difference between a 5 minute investigation and a frustrating hour of "it depends what code was deployed then". I have been in that hour a few times, and it is not super fun, honestly.

A PostgreSQL shape that stays debuggable

I prefer keeping the snapshot on the event or receipt row rather than on the user table:

create table auth_email_events (
  id bigserial primary key,
  user_id bigint not null,
  flow_type text not null,
  correlation_id uuid not null,
  raw_email text not null,
  normalized_email text not null,
  policy_snapshot jsonb not null,
  provider_status text not null,
  created_at timestamptz not null default now()
);

create index auth_email_events_lookup_idx
  on auth_email_events (correlation_id, created_at desc);

jsonb works well here because policy data evolves a bit. You may later add mx_check, tenant_policy, or alias_bucket without forcing a migration every time. I still keep core query fields, like normalized_email and correlation_id, as first-class columns so production queries stay fast and boring.

One practical rule: snapshot only the decision inputs you need for debugging. Do not dump full provider responses or unrelated request payloads into the same blob. That path gets messy, and kinda expensive, pretty fast. I have seen teams mix those concerns together and then regret it later, mostly because the table stops feeling clearly seperated by purpose.

What the API should persist at write time

The best moment to write the snapshot is inside the same transaction that creates the outbox or email event. If the worker computes policy later, you invite drift between what the API accepted and what the sender actually used.

My flow usually looks like this:

Normalize and classify the submitted email in the API layer.
Evaluate resend, risk, and template rules.
Write the auth event with policy_snapshot.
Insert the outbox row using the same correlation_id.

That sequence makes incident review much cleaner. If support asks why a reset message was skipped for an address that looked like tamp mail com, the answer comes from the stored event, not from guesswork about current code. If QA is testing OAuth recovery inboxes, they can line up the observed message with the backend event that created it instead of trusting mailbox timing alone. When a policy change happened last week and the complaint occured today, that extra context helps alot.

How this helps testing and support

This pattern helps in three places:

Support can inspect one event and see the exact policy decision.
Engineers can compare old and new rule versions during a rollout.
Test tooling can assert against backend evidence before waiting on inbox visibility.

That last point matters more than it seems. A lot of flaky email tests are really traceability problems. The mailbox is only the last hop. When the backend stores the policy snapshot and correlation id early, failures stop feeling random. You can tell whether the app suppressed the send, whether the worker processed it, or whether the inbox observer simply arrived late.

It also makes search and reporting better. If product wants to know how many addresses were suppressed by a new policy, SQL can answer that directly from the stored snapshot. No log spelunking, no replay job, less pain.

Q&A

Do I need a full policy engine for this?

No. Even a small ruleset benefits from snapshots if it influences auth email behavior.

Should I store the raw email too?

Usually yes, but keep access scoped. The normalized form explains behavior; the raw form helps diagnose user input edge cases.

Won't JSONB become a dumping ground?

It can, if you let it. Keep the snapshot small and decision-focused. Treat it like a receipt, not a warehouse.

Idempotent Signup Emails in REST APIs

kevindev — Tue, 11 Aug 2026 02:24:16 +0000

Signup email delivery looks simple until retries start stacking up. A client times out, the user taps submit again, and now the same account may get two confirmation emails with different lifetimes or different audit trails. In a REST API, that is not just annoying. It makes Authentication behavior harder to explain, harder to test, and harder to support once prod traffic gets noisy.

Teams searching for get temporary email flows or tp mail so are often trying to isolate inboxes for testing, but the deeper backend issue is idempotency. You want one logical signup attempt to produce one durable email intent, even if the transport layer or the worker retried more than once.

Why signup emails become duplicated

Most duplicate signup emails are caused by two things happening at the same time:

the API does not persist a stable request identity before enqueueing work
the email worker cannot tell whether it is handling a fresh event or a replay

That gap is usualy hidden when the happy path is fast. It appears later when mobile networks retry, reverse proxies replay on 502s, or a queue consumer restarts mid-send. If the only trace you keep is "email sent," your enviroment gives you no clean way to explain which request created which message.

The same thinking behind reset email isolation patterns applies here. An email event should be tied to durable state first, delivery second.

What state a REST API should persist

For signup confirmation, I like storing one row per logical email intent rather than one row per worker attempt. That row can be small:

signup_request_id
user_id
purpose
idempotency_key
token_hash
status
created_at
last_sent_at

The important part is not the exact column list. It is that your service can answer a few boring but critical questions:

Did this client already ask for a signup confirmation?
Is the current token still the valid one?
Was the email already queued or sent?
If a worker retries, should it send again or mark the attempt as duplicate?

When support teams chase weird aliases from staging, they also run into garbage inputs like tepm mail com. I do not use those strings as identifiers, but I do keep the raw submitted email in a scrubbed audit record so operaters can see what the client actually sent.

A small idempotent email design

The easiest design to maintain is usually:

Accept an idempotency key from the client, or derive one from a bounded request window.
Insert the signup intent in a transaction.
Enqueue an outbox job that references the inserted row.
Let the worker send only when the row is still in a sendable state.
Mark delivery timestamps on success without changing the logical intent identity.

In Node.js, the handler can stay pretty small:

await db.transaction(async (tx) => {
  const intent = await tx.signupEmailIntent.upsert({
    where: { userId_idempotencyKey: { userId, idempotencyKey } },
    update: {},
    create: {
      userId,
      purpose: "signup_confirm",
      idempotencyKey,
      tokenHash,
      status: "pending"
    }
  });

  await tx.outbox.insert({
    topic: "signup-email",
    aggregateId: intent.id
  });
});

That pattern isnt fancy, but it does something valuable: retries stop creating new logical work. The worker may still retry delivery, yet the API state stays stable. This also makes signup email state handling easier for frontend teams because the backend can expose a clearer status model.

How I test retries without guessing

My preferred test is not "did one email arrive?" It is "did the system preserve one logical signup intent while surviving repeated calls?" The flow is pretty simple:

Create a fresh user and isolated inbox alias.
Call the signup-confirm endpoint twice with the same idempotency key.
Assert that the database still has one logical signup intent row.
Assert that only one current token is valid.
Inspect the inbox and prove the observed message maps to that row.

If I need inbox verification, I keep the query narrow by alias and time window. That avoids false positives from older mailboxes and makes failures much less random. The test should also verify that a second worker retry does not produce a second valid token. Delivery may retry; meaning should not.

One subtle bug shows up when the API writes the outbox event before the intent row is committed. Under load, a worker can race ahead, fetch partial state, and send an email that no longer matches the final token. Those bugs are rare, but they are exactly the kind that become expensive once alerts start waking people up at 3 AM.

Checklist before you ship

One signup attempt maps to one durable email intent.
The REST API can answer whether a request was new or repeated.
Worker retries are recorded as attempts, not new business events.
The valid confirmation token is easy to identify in storage.
Inbox tests use isolated aliases and tight windows.
Audit fields are readable enough that an on-call engineer can diagnose the issue fast, even if the first report is a bit messy or worded akwardly.

Q&A

Should I block every repeated signup request?

Not necessarily. Repeated requests are normal. What you want is stable semantics, not fragile rejection logic. Return a safe response and keep the business event deduplicated.

Do I need an outbox if my mail provider already retries?

Yes, if you care about explaining backend behavior. Provider retries help delivery. The outbox helps your service keep a consistent story about what should have happened.

Is one inbox message always enough evidence?

No. A readable inbox is useful, but the stronger proof comes from joining message evidence back to stored API state. Without that, duplicate sends and stale tokens are harder to seperate.

Auth Logs Need Inbox Correlation IDs

kevindev — Sat, 08 Aug 2026 23:24:26 +0000

Verification email bugs are annoying because the failure usually lands between systems. The REST API says the request passed, the worker says it sent something, and QA says the inbox never showed the message. If those three views do not share one identifier, your incident review turns into log archaeology pretty fast.

What has worked better for me is adding a correlation id that travels from the auth request, into PostgreSQL, through the worker, and finally into any inbox assertion data. It is a small backend habit, but it makes Authentication issues much easier to explain and fix.

Why auth systems lose the email trail

Many auth services already store useful bits:

user id
email template
provider response id
retry count

That still is not enough when support asks a simple question: "Did this exact signup request produce the message that QA checked?"

The gap happens because delivery metadata and inbox metadata are often recorded in different places with different keys. A worker might log job_id, while the test harness stores only the recipient address. If the address was reused, or a resend happened, your evidence gets fuzzy. I have seen this go wrong even in otherwise clean systems, and the debugging cost was higher than the schema fix.

The correlation id shape I keep in PostgreSQL

I like giving every email-producing auth action one correlation_id at request time. That id gets written to the outbox row and also to a receipt table.

create table auth_email_receipts (
  id bigserial primary key,
  correlation_id uuid not null,
  user_id bigint not null,
  email_job_id bigint not null references email_jobs(id),
  template text not null,
  delivery_status text not null,
  provider_message_id text,
  inbox_observed_at timestamptz,
  inbox_observation_source text,
  created_at timestamptz not null default now()
);

The important part is not fancy SQL. It is that correlation_id survives every handoff. PostgreSQL is a good fit here because inserts are cheap, ordering is obvious, and querying one incident path stays boring. Boring is good, honestly.

I also keep inbox_observation_source optional. Sometimes the inbox check comes from Playwright, sometimes from a manual run, and sometimes not at all. Your source of truth should still be the backend evidence trail, not whether an inbox tool happened to respond that minute.

How the API and worker pass the same evidence forward

My preferred flow is:

The signup or password-reset endpoint creates correlation_id before the transaction commits.
The API writes the outbox row with that id.
The worker copies the same id into the delivery receipt when it claims and sends the job.
Test or QA tooling records inbox observations against the same id.

That means one query can answer the whole story:

select correlation_id, template, delivery_status, provider_message_id, inbox_observed_at
from auth_email_receipts
where correlation_id = $1
order by created_at asc;

When teams add abortable inbox polling on the client or in QA tooling, this shared id keeps polling results attached to the right auth event instead of just "whatever arrived for this mailbox". That matters more than people expect.

If I need an external mailbox for a staging check, I keep it narrow and contextual. A service like email temporary free can help validate that the user-visible message arrived, but I still treat it as supporting evidence. The receipt and outbox data should explain the backend path first.

Where inbox tools fit without owning the truth

Inbox tools are useful, but I try not to let them define correctness by themselves. Mailboxes are noisier than your database. Polling delays happen. Test addresses get reused. Someone pastes the wrong temp org mail into a manual checklist and now the investigation starts from a bad premise.

That is why I separate two questions:

Did the auth backend create and send the intended message?
Did an inbox observer later confirm the message was visible?

Those are related, but not identical. The first one should be answerable entirely from your application records. The second one adds user-facing confidence. For teams working on privacy-sensitive flows, invite email privacy checks are a good reminder that inbox validation should stay scoped and deliberate, not sprayed across logs.

One more small thing: make the correlation id visible in operator tooling. If an on-call engineer can paste one id into a dashboard and see the request, outbox row, worker attempt, and inbox observation together, the mean time to understand drops a lot. That sounds obvious, but many systems almost do this and then miss by one join key. I did that once, and it was a bit embarrasing.

Q&A

Should the user id be enough?

Usually no. A single user can trigger several auth emails in a short window, so you need event-level identity, not just actor-level identity.

Do I need a new table for this?

Not always, but a dedicated receipt table keeps the timeline cleaner than packing every state change onto the user record.

What if the provider already gives me a message id?

Keep it, but do not depend on it as your primary join key. You need an id created inside your system before the provider call happens.

DEV Community: kevindev

PostgreSQL Queues for Email Risk Reviews

Why email risk review queues get noisy

The PostgreSQL model that aged well for us

Claim rows with clear ownership

Where the authentication boundary should stay

Q&A

Should every flagged signup become a queued review?

Do I need Kafka for this?

What should I log for each decision?

REST Idempotency for Signup Email Jobs

REST Idempotency for Signup Email Jobs

Why signup emails duplicate so easily

The API contract that makes retries safe

A queue model that avoids double sends

Where temporary inboxes still help

A short review checklist

Q&A

Should I deduplicate only by email address?

What if the provider does not support idempotency keys?

Is eventual consistency a problem here?

PostgreSQL Audits for Email Change APIs

Why email change APIs are riskier than signup

The PostgreSQL records I keep for every email change

A REST API flow that survives retries and stale links

How I test the flow without trusting inboxes alone

Q&A

Why not store pending_email directly on the user row?

Should the verification token be unique per request?

What about rate limits?

Canonicalize Auth Emails Before You Rate-Limit

Why raw email strings create auth bugs

Canonicalize before policy and rate limits

A PostgreSQL receipt shape that stays reviewable

What to return from the REST API

Small checks that prevent painful regressions

Q&A

Should I canonicalize in the API or in the database?

Do I need a separate receipt row for every resend attempt?

Is this worth it for small apps?

Session Proof for Email Change APIs

Why email change APIs fail in quiet ways

Bind proof to the active session

A Node.js flow that survives retries

What to persist for operators

Testing without fooling yourself

Q&A

Should the verification link only work in the same browser?

Do I need this for low-risk products?

What if the user requested the change but lost the session?

PostgreSQL Rules for Burner Email Signups

Why signup rules drift over time

Model the policy in PostgreSQL first

Keep the API response boring and consistent

Add reviewable signals instead of hidden magic

Questions teams usually ask

Should we block every disposable domain?

Should the domain list live only in Redis?

What is the most common mistake?

Node.js Audit Trails for Email Change Flows

Why email change flows become hard to explain

Model the request as a state machine

Keep the audit trail append-only

A compact Node.js implementation

Where disposable inboxes actually help

Q&A

Should the old email always confirm the change?

Where should expiry live?

Is this too much for a small app?

PostgreSQL Leases for Resend Email APIs

Why resend endpoints drift out of sync

Lease the send in PostgreSQL, not in app memory

A schema that keeps retries boring

REST API behavior that stays honest

Where disposable inboxes fit

Q&A

How long should the lease last?

Should I delete failed intents?

Is this overkill for a small app?

Version Auth Emails With Attempt Receipts

Why not store `pending_email` directly on the user row?