DEV Community: kevindev

Idempotent Verification Emails in Node APIs

kevindev — Sat, 25 Jul 2026 05:24:07 +0000

Verification emails look simple until retries, worker restarts, and impatient users all hit the same POST /verify-email flow. In most systems the real bug is not SMTP delivery. It is missing idempotency rules between your REST API, job table, and auth state. I have seen teams patch this with boolean flags, and it works... right until traffic spikes a bit.

The failure mode is usually a race, not SMTP

The common sequence is boring:

User signs up.
API inserts the account row.
API or worker enqueues a verification email.
User clicks resend because the first message is slow.
Two workers now think they should send the same intent.

If your system stores only sent=true, you cannot tell whether a send is in progress, already committed, or safe to retry. That gap creates duplicate emails, stale tokens, and support noise. It also makes debugging kinda annoying because logs often show "success" for both attempts.

What helped me most was treating verification email delivery as a state machine owned by the backend, not as a side effect hidden behind a mail client wrapper.

A small state model fixes most duplicate sends

For verification flows, I like one row per delivery intent with these fields:

user_id
purpose such as signup_verification
idempotency_key
state in pending | claimed | sent | consumed | failed
token_hash
claimed_at, sent_at, failure_code

The rule is simple: the API creates or reuses the current intent, and the worker may only send after it atomically claims the row. That removes the "did two workers race?" question from app code and pushes it into data consistency, where PostgreSQL is much better equiped to help.

I also keep the idempotency key stable for a short replay window. For example, if the same authenticated user hits resend within five minutes, the API can return 202 Accepted and point to the existing intent instead of minting a new token each time. That makes auth behavior easier to reason about, and users get a more predictable flow.

Node.js example: claim work before sending

Here is the shape I prefer in a Node.js service:

async function claimVerificationIntent(db, userId) {
  const result = await db.query(`
    update email_delivery_intents
       set state = 'claimed',
           claimed_at = now()
     where id = (
       select id
         from email_delivery_intents
        where user_id = $1
          and purpose = 'signup_verification'
          and state = 'pending'
        order by created_at asc
        for update skip locked
        limit 1
     )
    returning id, token_hash, idempotency_key
  `, [userId]);

  return result.rows[0] ?? null;
}

Two details matter more than the SQL syntax:

for update skip locked prevents workers from claiming the same pending row.
The state transition happens before the email provider call, so your retry logic knows whether it is replaying a claim or creating new work.

After a successful send, update the same row to sent and persist the provider message id if you have one. If the provider times out, do not blindly insert a second intent. First inspect whether the original claim may still finish. This is where many APIs get a little messy and start spraying duplicates.

On the API side, I keep resend logic explicit:

if (existingIntent && existingIntent.state !== 'failed') {
  return { status: 202, intentId: existingIntent.id };
}

await createPendingIntent({ userId, purpose: 'signup_verification' });
return { status: 202 };

This approach fits nicely with other backend patterns too. If you already use an outbox table for domain events, the verification intent can either become the outbox record or reference it directly. The point is to keep one source of truth for "should an email be sent?".

Where a temporary email address helps in testing

I do not use email sandboxes only for UI tests. They are useful for backend contract checks, especially when you need to prove that one resend request still maps to one effective email intent. A temporary email address is handy when you want fresh inbox state per test case without leaking messages into shared accounts.

For example, one practical pattern is:

create a user
trigger signup verification twice with the same auth context
assert one sent transition in the database
inspect one inbox for one token

That kind of workflow pairs well with isolated inbox checks and safer invite email debugging, because both push teams toward cleaner evidence when they debug email behavior.

If you need a disposable inbox during local development, keep it a tiny part of the system design rather than the center of it. I sometimes use tools like temp mail so for quick manual verification, but the stronger win is still your database contract. Even if someone types tempail mail into a note or test case, the backend should remain deterministic.

Q&A

Should I create a new token on every resend?

Not always. If the previous token is still valid and the user is within a short replay window, reusing the same intent is often simpler and less error-prone. Rotate only when your security model or abuse controls actually require it.

What should the API return to clients?

I prefer 202 Accepted for resend operations because the actual delivery is asynchronous. The response can include a stable intent identifier, which is more useful for tracing than a vague "email sent" message that maybe was not sent yet.

Does this pattern only help authentication flows?

No. Password reset, invite acceptance, magic links, and billing notifications all benefit from the same model. Once you separate intent creation from send execution, the rest of the system gets easier to test and reason about, even if the first version feels a bit more work.

The boring conclusion is the useful one: model email delivery as backend state, claim work before sending, and keep resend semantics explicit. Do that, and a lot of auth-email flakiness just... stops happening.

Lease Email Jobs Before Your Worker Sends

kevindev — Mon, 20 Jul 2026 11:24:44 +0000

Duplicate auth emails are rarely caused by one big bug. More often, the API is fine, the queue is fine, and the worker logic is almost fine. Then a timeout lands between "picked job" and "marked sent", another worker retries, and a user gets two reset links. That kind of issue is annoyng because each individual component looks healthy in isolation.

When you maintain Authentication flows, the fix I trust most is not more retry logic. It is a lease on the email job itself. Before a worker sends anything, it claims the row for a short window, records who owns it, and only then continues. The result is much calmer behavior under retries, crashes, and horizontal scaling.

Why email workers still duplicate sends

Most duplicate sends happen in one of these moments:

a worker crashes after calling the provider but before updating the database
two workers poll the same ready job at nearly the same time
a retry policy has no clear ownership boundary
delivery polling from a tempail mail inbox gets mixed with the original send timeline

This is where a lease is more useful than a plain status column. pending and sent are not enough once you have more than one consumer. You also need "claimed until" and "claimed by", so another worker can see that the job is already in progress and back off.

If you already use database-backed signup delivery, leasing is a natural next step. The outbox tells you what should be sent. The lease tells you who is allowed to send it right now.

The lease model I prefer

My baseline table usually has these fields:

id
template
recipient
payload
status
lease_owner
lease_expires_at
sent_at
attempt_count

The key rule is simple: only rows with an expired lease, or no lease at all, are eligible to be claimed. PostgreSQL makes this clean with FOR UPDATE SKIP LOCKED, which is designed for concurrent workers that should not block each other unnecessarily (https://www.postgresql.org/docs/current/sql-select.html).

I also keep the lease short, usually 30 to 90 seconds. Long enough for one delivery attempt, short enough that a crashed worker does not stall the pipeline for ages. If your provider latency is high, measure first instead of guessing. Google's distributed systems guidance has long pushed engineers toward observable time budgets rather than wishful defaults (https://sre.google/sre-book/monitoring-distributed-systems/). Same lesson here, realy.

A PostgreSQL query that claims work safely

Here is the shape I like for claiming one job:

with next_job as (
  select id
  from email_jobs
  where status = 'pending'
    and (lease_expires_at is null or lease_expires_at < now())
  order by created_at
  for update skip locked
  limit 1
)
update email_jobs ej
set lease_owner = $1,
    lease_expires_at = now() + interval '45 seconds',
    attempt_count = attempt_count + 1
from next_job
where ej.id = next_job.id
returning ej.id, ej.recipient, ej.template, ej.payload, ej.attempt_count;

Three details matter a lot:

Claim and update in one statement.
Increment attempts when the lease is taken, not after the send.
Return the payload immediately so the worker does not re-read stale state.

That contract makes Node.js workers much easier to reason about. A worker either owns the lease or it does not. There is less fuzzy middle state, which is where duplicated behavior loves to live.

How to keep retries boring

After the send succeeds, update the row with status = 'sent', clear the lease, and store a provider message ID if you have one. If the send fails with a retryable error, leave status as pending and let the lease expire naturally. If it fails permanently, mark it failed and stop looping.

For Auth flows, I also recommend tying the email job to a server-side token version, not just a raw recipient. If two password reset requests arrive quickly, you want the newest token to invalidate the older one, even if an older job sneaks through later. The delivery pipeline and the token model should protect each other.

When you test this behavior, isolated inboxes help, but they are only supporting evidence. I prefer to combine the lease audit trail with contract checks around email APIs, then use a scoped inbox from temp mail so when I want to verify that exactly one human-visible message arrived. That balance keeps the design backend-first instead of mailbox-first.

A few logs make the system easier to trust:

job id
lease owner
lease expiration
token version
provider message id

If one of those is missing, debugging gets slower than it should be. You can still fix the incident, but you will burn more team energy doing it, which is never great and kinda avoidable.

Q&A

Why not just mark rows as processing?

Because processing without an expiry becomes sticky after crashes. A lease says "processing until this exact time", which is much safer.

Should the lease duration match provider timeout?

Close to it, yes, but leave a little margin for serialization and DB update time. Do not make it huge "just in case". That tends to hide dead workers.

Does this replace idempotency keys?

No. Provider-side idempotency is still useful. The lease protects your worker coordination layer; provider idempotency protects the outbound call. Together they fail much more gracefuly than either one alone.

Replay Windows for Email Change Tokens

kevindev — Mon, 20 Jul 2026 02:24:37 +0000

Changing an account email looks simple in product mocks, but the backend path is easy to get wrong. The request touches identity, notification, and recovery flows at the same time, so a small retry bug can leave a user with two valid links or a silently stale address. I have seen this happen in otherwise careful services, especialy when the API treated "token created" as the end of the job.

Why email change flows replay more than teams expect

Replay bugs usually show up at the boundary between the authenticated request and the later confirmation click. A POST /account/email-change call writes a pending address, creates a token, and sends a message. Then the user opens the mail client twice, the gateway retries once, or support triggers a resend while the first token is still alive.

Three patterns cause most of the mess:

The service stores only the newest token, so it cannot explain which link was clicked.
Resend logic invalidates too late, leaving a short period where two links both work.
Audit logs show "email updated" but not which request or token actually did it.

For auth systems, that is not just annoying. Email is often the recovery channel and the notification channel, so a replay bug can realy confuse incident response. When a user says "I clicked the older email by mistake", the system should have a crisp answer instead of a shrug.

The token contract I use in production

The contract I like is boring on purpose:

users.email stays unchanged until the confirmation click succeeds.
email_change_requests stores the old address, the proposed address, a token hash, expiry, and a superseded_at timestamp.
Every resend creates a new row and supersedes earlier still-open rows for the same user.
The confirmation endpoint accepts exactly one active row inside a small replay-safe transaction.

That last point matters more than teams first think. If two browser tabs submit the same token within a second, I want one winner and one clean "already used" response. If a user opens an older link after a resend, I want "superseded" and not a vague invalid-token page.

I also keep the reason code close to the row. States like pending, confirmed, expired, and superseded are enough for most products. You do not need a large workflow engine here, but you do need a lifecycle that support and security can inspect in minuts.

One small practice has saved me more than once: never reuse the same row for a resend. A fresh row keeps the audit trail legible and avoids state that is slighly impossible to reason about later.

A Node.js and PostgreSQL implementation

My write path usually starts by locking the user row, then creating a pending request:

await db.tx(async (trx) => {
  const user = await trx.one(
    `select id, email
     from users
     where id = $1
     for update`,
    [userId]
  );

  await trx.none(
    `update email_change_requests
     set superseded_at = now()
     where user_id = $1
       and confirmed_at is null
       and superseded_at is null
       and expires_at > now()`,
    [user.id]
  );

  await trx.none(
    `insert into email_change_requests
      (user_id, current_email, next_email, token_hash, expires_at, request_id)
     values ($1, $2, $3, $4, now() + interval '20 minutes', $5)`,
    [user.id, user.email, nextEmail, tokenHash, requestId]
  );
});

The confirmation path is where the replay guard lives. I normally update the request row and the user row in one transaction, with a predicate that only matches an active token once:

with claimed as (
  update email_change_requests
     set confirmed_at = now()
   where token_hash = $1
     and confirmed_at is null
     and superseded_at is null
     and expires_at > now()
  returning user_id, next_email
)
update users
   set email = claimed.next_email
  from claimed
 where users.id = claimed.user_id
returning users.id, users.email;

If that second statement returns zero rows, I look up the request state and return a precise response. 410 Gone works well for expired or superseded tokens; 409 Conflict is reasonable for a token already consumed. The important thing is consistency, because clients and support tooling both start to depend on it.

The reason I prefer this design in a REST API is that it scales without extra magic. PostgreSQL handles the concurrency. Node.js just carries request ids, auth context, and metrics. There are fewer hidden dependancies, which makes on-call debugging calmer.

According to the 2024 Verizon Data Breach Investigations Report, stolen credentials and auth abuse remain a major factor in real incidents, which is why I do not like fuzzy confirmation flows around account identity changes: https://www.verizon.com/business/resources/reports/dbir/. Email change is not the only control, but it is part of the trust boundary.

What I verify in staging before shipping

I do not stop at "mail arrived". For this feature, I want four checks:

A first token confirms the change and updates the account exactly once.
A resend marks the older token as superseded before the new message is sent.
A double-click on the same confirmation link produces one success and one deterministic failure.
Audit records join cleanly by user id, request id, and token state.

This is where isolated inboxes help, even if the article itself is not about email tooling. Teams often leave fixture labels like tempail mail or tamp mail com in staging helpers, and that is usually a sign the test path grew organically rather than intentionally. I try to keep one inbox per test run and one request id per email-change attempt.

If you already have reset delivery drift checks in place, reuse the same assertion style here. The browser test should not just open the latest message it sees. It should target the exact request id or scenario id. That matches the same thinking behind stable inbox scenario ids, and it makes flaky auth tests a lot easier to explain.

One more thing: emit a support-facing event when a token is superseded. Not because the product UI always needs it, but because the audit trail often does. When somebody says "your system changed my address without warning", that breadcrumb matters a ton.

Q&A

Should I invalidate older email-change tokens immediately on resend?

Yes, if the user intent is "use the latest email only". Keeping parallel valid tokens almost never helps, and it makes abuse analysis harder.

Do I need a separate table for email-change requests?

I think so. Reusing a generic token table can work, but teams often regret it once they need better audit detail, clearer states, or support tooling.

What if the user changes the target address twice in one session?

Create a new request each time and supersede the old one. That keeps the flow honest and avoids teh weird case where one confirmation email mutates into another meaning.

PostgreSQL Outboxes for Signup Emails

kevindev — Sun, 19 Jul 2026 14:24:40 +0000

When signup emails start missing in production, the bug is usualy not inside the SMTP provider. It is often in the handoff between your REST API, your database write, and the worker that sends the message later. That is why I keep coming back to a PostgreSQL outbox design for signup mail instead of pushing directly to a queue in the request path.

The reason is boring in a good way. If the user row commits but the queue publish fails, support gets a "created account, no email" ticket. If the client retries during a slow network hop, you may enqueue two welcome messages. If staging uses random inboxes and nobody ties them back to one request id, debugging gets messy real fast. An outbox row makes those cases more tractable.

Why signup email sends fail in boring ways

The request flow looks simple:

POST /signup
create user
generate verification token
queue email job
return 201

What breaks is not the happy path, it is the seam between steps 3 and 4. Queue publish calls can timeout after your transaction committed. API clients can retry even when the first response was already on the wire. Workers can process the same job twice after a crash. None of that is dramatic, but it adds the kind of edge-case noise engineers hate cleaning up at 2 a.m.

I also see staging searches get muddy because people leave notes like tamp mail com or temp gamil com in tickets and shell history. That is not the root cause, but it is a sign the verification process is fuzzy and too dependent on manual inbox chasing.

The PostgreSQL outbox shape I keep coming back to

I prefer storing the email intent in the same transaction as the user and token write. A minimal outbox table can be:

create table email_outbox (
  id bigserial primary key,
  event_type text not null,
  aggregate_id uuid not null,
  dedupe_key text not null unique,
  payload jsonb not null,
  status text not null default 'pending',
  available_at timestamptz not null default now(),
  sent_at timestamptz,
  created_at timestamptz not null default now()
);

The important field is dedupe_key. For signup mail, I usually build it from a stable operation id such as signup:<user_id>:verify-email:v1. If the client retries the same request, the insert will conflict cleanly instead of creating another pending email. That ends up working nicely beside patterns like concurrency keys for email checks, because both approaches force the system to name one operation clearly.

Then the write transaction stays boring:

await db.tx(async (trx) => {
  const user = await createUser(trx, input);
  const token = await createVerifyToken(trx, user.id);

  await trx.none(
    `insert into email_outbox
       (event_type, aggregate_id, dedupe_key, payload)
     values ($1, $2, $3, $4)
     on conflict (dedupe_key) do nothing`,
    [
      "signup.verify_email",
      user.id,
      `signup:${user.id}:verify-email:v1`,
      { userId: user.id, tokenId: token.id, email: user.email }
    ]
  );
});

I like this because the API promise is modest and honest. If the transaction commits, the intent to send exists durably in PostgreSQL. You can let a worker poll the outbox, or stream it with logical decoding later if your system grows up and needs it. Do the simple thing first.

A REST API flow that stays idempotent under retries

The request handler should not say "email sent". It should say "signup accepted, email delivery scheduled" and return enough identifiers to debug later. I tend to include:

user_id
operation_id
email_delivery_state

The worker then claims pending rows with for update skip locked, sends one message, and updates status to sent or failed. PostgreSQL documents SKIP LOCKED as a way to avoid waiting on rows already locked by another transaction, which is exactly why it fits small outbox workers so well (https://www.postgresql.org/docs/current/sql-select.html).

What I try to avoid is pushing transport-specific details into the API contract too early. Provider message ids are useful, but they should be attached to the outbox record, not replace it. Support and staging tools need one stable handle from the app domain first. That also makes a privacy review for magic-link flows much easier, because you can audit what data left the system without scraping random worker logs.

How I verify the pipeline in staging

My staging check is very small:

create the signup through the public API
fetch the outbox or delivery record by operation id
wait for a terminal state
inspect the rendered email in a temporary inbox

That last step matters, but I do not want the inbox to be the only truth source. Teams often search for something like temp mail so when they really need to answer a backend question: did we persist the send intent, and did exactly one worker consume it? The inbox confirms rendering and transport. PostgreSQL confirms system behavior. You need both, or at least you probly do once the app has real traffic.

I also keep the worker batch size small in staging. Five rows at a time is enough for most checks, and it makes failure review much easier than draining fifty mixed events in one loop.

Q&A

Why not publish directly to the queue inside the request?

You can, but then your API success path depends on two systems committing in one moment. The outbox reduces that coupling and gives you a recovery surface when the queue or provider is having a weird day.

Does this only help Node.js apps?

Not at all. I use Node.js a lot, but the pattern is database-first. Any stack that can write the business row and outbox row in one transaction can use it.

When should I move past polling workers?

Only when polling is proven too slow or too expensive. For most signup email volume, a simple poller with clear metrics is easier to run, easier to fix, and honestly less fancy in the best way.

If your signup flow keeps losing email intent at the edges, an outbox table is one of the highest-leverage boring fixes I know. It keeps the REST API contract honest, lets PostgreSQL do the coordination work it is already good at, and makes email debugging feel a lot less random.

Delivery Receipts for Async Email APIs

kevindev — Fri, 17 Jul 2026 08:24:59 +0000

When an app sends signup, reset, or approval mail asynchronously, the first bug report is rarely "email did not send". It is more often "support cannot tell what happened". The API returned 202, the queue looked healthy, and the user still asks where the message went. That gap is why I like exposing a delivery receipt contract in the REST API itself instead of treating email as a black box.

In backend teams, this becomes much easier to reason about when one request maps to one operation record, one worker decision, and one status surface the client or support tool can query later. The idea is not flashy, but it saves a lot of guesswork and a fair bit of noisy log diving too.

Why async email APIs become hard to support

The usual flow looks harmless:

POST /signup-email
Store a job
Push to queue
Return 202 Accepted

The problem is that 202 says "accepted for processing", not "we can explain the outcome later". In many systems, once the request leaves the API process, observability gets fragmented. Queue logs sit in one place, provider webhooks in another, and support notes in a third. By the time someone investigates, the timeline is kinda blurry.

That blur gets worse under retries. Mobile networks retry. API gateways retry. Humans click resend. If you do not keep a durable receipt row, two operations can look the same from the outside even though one was superseded. I have seen teams add more logging to fix this, but logs alone are a weak contract.

The receipt contract I expose in a REST API

My preference is simple:

POST /email-deliveries creates or reuses an operation
the response includes delivery_id
GET /email-deliveries/:delivery_id returns the current state
workers update that state as they enqueue, send, retry, or fail

That gives clients and internal tools one durable lookup key. A response can be as small as:

{
  "delivery_id": "em_01JY7QY2R5N6YQ6R6P2M",
  "status": "queued",
  "created_at": "2026-07-17T08:22:30Z"
}

Later, the status endpoint can expose states such as queued, sent, provider_rejected, expired, or superseded. I try to keep the state machine boring on purpose. Fancy event names are cute for a week and annoying for years.

This is also where I connect backend mail flows to release-gate inbox validation. If a test or operator knows the delivery_id, the inbox check becomes a verification step, not the only source of truth.

A Node.js persistence model that makes retries boring

In Node.js, I usually persist two things:

an email_deliveries row that represents the public operation
an outbox or job row that represents work still to do

The first row should survive provider weirdness. The second row can be retried, replaced, or delayed without changing the external contract. A minimal table shape might be:

create table email_deliveries (
  id text primary key,
  purpose text not null,
  recipient_hash text not null,
  status text not null,
  request_id text not null,
  provider_message_id text,
  last_error text,
  created_at timestamptz not null default now(),
  updated_at timestamptz not null default now()
);

And a thin service layer:

type CreateDeliveryInput = {
  purpose: "signup" | "reset" | "approval";
  recipientHash: string;
  requestId: string;
};

export async function createDelivery(input: CreateDeliveryInput) {
  return db.tx(async (trx) => {
    const existing = await trx.oneOrNone(
      `select id, status
       from email_deliveries
       where request_id = $1`,
      [input.requestId]
    );

    if (existing) return existing;

    const delivery = await trx.one(
      `insert into email_deliveries
         (id, purpose, recipient_hash, status, request_id)
       values ($1, $2, $3, 'queued', $4)
       returning id, status`,
      [newDeliveryId(), input.purpose, input.recipientHash, input.requestId]
    );

    await enqueueSendJob(trx, delivery.id);
    return delivery;
  });
}

There are fancier versions of this, but the main rule is: use one stable id for the operation the caller cares about. Do not make the client reverse-engineer queue IDs, webhook payload IDs, and provider IDs just to answer a basic support question. It sounds obvious, yet a lot of APIs still do it half way.

How I test delivery status without trusting the inbox alone

Inbox checks are useful, but they are the end of the chain, not the whole chain. My staging tests usually assert four things:

the POST response returns a stable delivery_id
repeated requests with the same request id do not create extra operations
the worker transitions the receipt row through expected states
the inbox message corresponds to that exact delivery record

That last point matters. If the inbox is the only assertion surface, a stale message can make a test pass for the wrong reason. The same mindset behind rollback email checks applies here: delivery evidence should line up with system state, not replace it.

For staging, I sometimes use a fake email address service such as tempmailso to confirm the rendered message body and links. It is handy for transport checks, but I still compare the observed email against the delivery receipt row before I call the run good. Otherwise, a recycled alias from tepm mail com notes or an old dummy e mail in a script can muddy results in ways that are frankly annoyng.

If you want one lightweight metric, start with receipt resolution time: how long it takes for a delivery to move from queued to a terminal state. Google’s SRE workbook stresses measuring user-visible completion around asynchronous work rather than only subsystem health, which is a useful framing here too (https://sre.google/workbook/implementing-slos/).

Q&A

Should the client poll the receipt endpoint?

Usually yes, at least for flows where the user is waiting on a message. Keep the polling window short, then fall back to a "still processing" UI instead of pretending the send is instant.

Do I need provider webhooks to make this useful?

Not strictly. You can start with queued and sent states from your worker. Webhooks improve accuracy later, especialy for bounces and rejects.

What if one user asks for multiple emails quickly?

That is fine if each request has a clear purpose and request id. The hard part is not concurrency itself, it is ambiguity about which operation your UI or support team is looking at.

Checklist

Return a stable delivery_id from the write API.
Keep a receipt row separate from the queue job row.
Make retries idempotent with a request-scoped key.
Treat inbox checks as confirmation, not ground truth.
Prefer a small, explicit state machine over provider-specific jargon.

Once you add delivery receipts, async email APIs feel much less magical and much more maintainable. Support gets answers faster, tests stop leaning on luck, and the backend contract becomes easier to evolve without breaking every surrounding tool.

Versioned Reset Tokens in PostgreSQL

kevindev — Thu, 16 Jul 2026 23:25:00 +0000

Password reset flows look routine until the first real retry storm lands. A mobile client resubmits, a worker drains late, or a user clicks the older link after a newer one was issued. If the backend does not make token ownership explicit, support ends up chasing inbox screenshots instead of database facts. I have seen this enough times that I now treat reset email delivery as a state-management problem first and a mail problem second.

The pattern here is close to the same lessons behind PostgreSQL outbox checks and isolated inbox validation: one user intent should map to one current backend truth. For Authentication systems that already lean on PostgreSQL, versioned reset tokens are a simple way to keep that truth inspectable.

Why password reset flows drift under retries

The common failure shape is boring, which is why it slips through reviews:

POST /password-reset creates a token row.
An email job is queued in a separate step.
The client retries before the first response is observed.
A second token or second job is created with just enough timing difference to confuse everyone.

Nothing looks dramatic at first. The API still returns success. The worker still sends. The inbox still shows a reset email. But later you discover the link the user clicked was already obsolete, or that two links were valid longer than intended. That is not just messy, its a contract problem.

I prefer deciding one rule clearly: every reset attempt gets a token version, and only the newest committed version is allowed to survive as current. Older versions can exist for audit, but they should stop being actionable immediately.

The versioned token contract I prefer

My default contract is pretty simple:

Lock the user reset state in one transaction.
Increment a version whenever a new reset intent is accepted.
Store the token hash and expiry beside that version.
Emit one outbox event keyed by user_id plus version.
Let the worker send only if the referenced version is still current.

This does two useful things. First, retries become inspectable because you can answer "which token version won?" with a query instead of a guess. Second, worker lag becomes tolerable. Even if an older job wakes up late, it can re-check state and skip itself.

For backend teams, that skip step is where a lot of reliability comes from. People sometimes think on conflict do nothing is the whole story. It helps, but it does not answer whether the event still matches the latest reset truth. You need that second check or you eventualy trust queue timing more than data.

A PostgreSQL schema that makes stale mail obvious

This is the smallest shape I tend to like:

create table password_reset_state (
  user_id bigint primary key,
  token_hash text not null,
  version integer not null,
  expires_at timestamptz not null,
  updated_at timestamptz not null default now()
);

create table email_outbox (
  id bigserial primary key,
  topic text not null,
  dedupe_key text not null unique,
  payload jsonb not null,
  created_at timestamptz not null default now()
);

And the transactional write is straightforward:

await db.tx(async (trx) => {
  const state = await trx.oneOrNone(
    `select version
       from password_reset_state
      where user_id = $1
      for update`,
    [userId]
  );

  const nextVersion = (state?.version ?? 0) + 1;

  await trx.none(
    `insert into password_reset_state (user_id, token_hash, version, expires_at)
     values ($1, $2, $3, $4)
     on conflict (user_id) do update
       set token_hash = excluded.token_hash,
           version = excluded.version,
           expires_at = excluded.expires_at,
           updated_at = now()`,
    [userId, tokenHash, nextVersion, expiresAt]
  );

  await trx.none(
    `insert into email_outbox (topic, dedupe_key, payload)
     values ('password_reset', $1, $2::jsonb)
     on conflict (dedupe_key) do nothing`,
    [
      `password_reset:${userId}:${nextVersion}`,
      JSON.stringify({ userId, version: nextVersion })
    ]
  );
});

The worker should read password_reset_state before delivery and compare versions. If the payload says version 4 but the table is now version 5, skip send and mark the event stale. It is a tiny read, but it makes debugging much less anoying later.

What I validate in staging before calling it done

I still use inbox checks in staging, but only as delivery evidence. The authoritative assertions live in backend state:

a retried reset request should leave one current token version
an older outbox event should not send after supersession
the clicked link should map to the latest committed version
logs, worker events, and audit rows should agree on the same version

This is where temporary inbox tooling can help without becoming the source of truth. A temporary email or a disposable email address generator is useful when I need to prove the message rendered and arrived. But I do not treat the inbox as the contract itself. If a team starts saying "the tepm mail com check looked okay" while the database story is fuzzy, that is usualy a sign the test setup is compensating for a backend gap.

One more practical rule: keep reset TTL short and version checks explicit in logs. When support gets a stale-link report, you want to know whether the user clicked version 2 after version 3 had already replaced it. That answer should be cheap to get, not buried in a worker trace from six systems ago.

Q&A

Should older reset tokens be deleted immediately?

Not necessarily. I prefer keeping them for audit for a short period, but marking them unusable as soon as a newer version becomes current.

Is one table enough for this flow?

For many services, yes. A single current-state table plus an outbox table keeps the flow simple and debuggable. If volume grows, the contract still holds.

Does this only matter for password resets?

No. The same pattern works for magic links, verify-email flows, and invite acceptance. Password reset just makes the failure mode show up faster because users retry when they are already frustrated.

Request IDs for Safer Signup Email APIs

kevindev — Thu, 16 Jul 2026 17:24:37 +0000

Signup email flows rarely break because SMTP is mysterious. They break because the API and the mail side stop agreeing about which request is the real one. A user double-clicks, a mobile client retries, or a worker wakes up late, and now the service has two believable stories. I keep seeing the same thing in backend systems: once request identity is fuzzy, debugging gets annoyng fast.

That is why I like carrying one request ID from the signup endpoint all the way into the email outbox. It is close in spirit to run-scoped notification tracing and the sort of email API triage in CI that saves time later. For REST API teams, the main win is not prettier logging. The win is having one durable key that tells your database, queue, and test suite they are talking about the same signup attempt.

Why signup email APIs get messy under retries

The usual bug pattern looks like this:

POST /signup creates the user and enqueues a welcome or verify email.
The client times out before it sees the response.
The client retries with the same form data.
The backend creates another mail event because it cannot prove the first one already "won".

At that point the inbox may still look fine. Maybe both messages arrive. Maybe only one does. Maybe the second one lands first. What matters is that the system has no clean contract anymore. If support asks which verification link should be trusted, the answer becomes "it depends," which is prety much the answer you do not want.

For authentication-heavy services, I prefer treating signup mail like any other stateful side effect: bind it to an explicit request record, make dedupe visible in storage, and let workers send only the event that still matches the current state.

The request ID contract I like in backend services

My default contract is simple:

The client sends or receives a request ID for the signup attempt.
The API stores it beside the pending verification state.
The outbox event uses the same request ID as its dedupe key.
The worker checks that the request ID is still current before sending.

This keeps retries boring, which is the right outcome. If the same signup call is replayed, the API can return the existing result instead of producing a second email event. If you intentionally start a fresh attempt, you rotate the current request ID and older events become stale by definition.

I also like this pattern because it sharpens ops conversations. Engineers stop saying "some signup email probably got duplicated" and start saying "request req_9b2... was superseded before delivery." That is a much better place to debug from, even when the wording is a bit nerdy and maybe a little over-specific.

A small Node.js flow that keeps mail events honest

This does not need a huge framework. A compact transaction plus an outbox table is enough for many teams:

await db.tx(async (trx) => {
  const signup = await trx.oneOrNone(
    `select user_id, current_request_id
       from signup_email_state
      where user_id = $1
      for update`,
    [userId]
  );

  const requestId = incomingRequestId ?? crypto.randomUUID();

  await trx.none(
    `insert into signup_email_state (user_id, current_request_id, updated_at)
     values ($1, $2, now())
     on conflict (user_id) do update
       set current_request_id = excluded.current_request_id,
           updated_at = now()`,
    [userId, requestId]
  );

  await trx.none(
    `insert into email_outbox (topic, dedupe_key, payload)
     values ('signup_verify', $1, $2::jsonb)
     on conflict (dedupe_key) do nothing`,
    [requestId, JSON.stringify({ userId, requestId })]
  );
});

The worker step is where people often cut corners. I would not. Before sending, read signup_email_state again and verify the payload request ID is still the current one. If not, skip the send and mark the event stale. That extra query is cheap, and it removes a lot of "why did the older link win?" confusion.

How I validate staging without trusting the inbox alone

I do use inbox tooling in staging, but only as transport evidence. The authoritative check is still backend state. A delivered message proves reachability; it does not prove your API chose the correct request. That distinction matters more than teams expect.

My test checklist is usualy:

the same request ID cannot enqueue multiple active events
a superseded request ID never sends after a newer signup attempt
the clicked verification link maps to the current request record
logs and metrics include the same request ID end to end

If I need a disposable inbox for smoke tests, I keep it small and contextual. Something like temp mail so can help confirm a real message was emitted, while a fake emails generator setup is useful for quick staging runs. But I still verify the request record in the database before I call the flow good. Otherwise teams end up trusting inbox behavior alone, and then weird notes about tepm mail com or "the second email looked right" start creeping into the runbook.

One more rule that has saved me a few times: expire the request ID with the verification attempt, not with the job runtime. Workers can lag. Your contract should still be crisp when they do.

Q&A

Should the client always provide the request ID?

Not necessarily. The server can mint it and return it in the first response. The important bit is that retries reuse the same identity when they mean the same logical action.

Is the outbox dedupe key enough by itself?

No. It prevents duplicate inserts, but you still need a current-state check before sending, or an older event may stay believable for too long.

Does this only matter for verification emails?

Nope. Password reset, invite, and magic-link flows all benefit from the same contract. Signup just tends to expose the mess sooner.

Idempotent Verify Email APIs in PostgreSQL

kevindev — Wed, 15 Jul 2026 20:24:30 +0000

Verify-email endpoints look simple until retries show up. A user taps resend twice, the client retries on a slow network, and suddenly your service has two valid links in flight or two emails racing through the queue. That is why I treat verification mail as an API contract problem first, not just a delivery problem.

I like starting from the same lessons behind duplicate signup email prevention and preview inbox isolation: one user action should map to one clear backend state transition. For Authentication flows, PostgreSQL is usualy the easiest place to enforce that contract because it already owns consistency, ordering, and conflict handling.

Why verify-email endpoints are easy to duplicate

The common failure mode is split ownership:

The API updates users.email_verification_token.
A queue job is emitted in a separate step.
A retry repeats the API call before the first job finishes.
Two messages now describe slightly different truth.

Everything can still look healthy in logs. The API returns 202, the worker sends, and the UI gets a nice success toast. But later, support sees links that fail, or a stale email is clicked after a newer one was issued. Thats not a mail provider problem. It is a backend contract leak.

For resend flows, I prefer deciding one thing explicitly: is a repeated request supposed to reuse the same active verification intent, or supersede it with a newer one? Either choice is fine, but the system should say so in data, not in vague worker timing.

The PostgreSQL contract that keeps retries safe

The pattern I trust is:

Resolve the current verification state inside one transaction.
Either reuse the active token row or replace it with a higher version.
Insert exactly one outbox event keyed to that chosen version.
Commit once.
Let workers send only committed, non-superseded events.

That gives the API an idempotent surface. If the client repeats the same resend request with the same idempotency key, the database can point back to the same verification version instead of minting fresh chaos. If you intentionally issue a new token, the previous version becomes clearly outdated and workers can skip it.

In practice, I store both a stable verification purpose and a monotonicaly increasing version. The outbox payload includes user_id, purpose, and version. When the worker renders the email, it rechecks that the referenced version is still current before sending. This extra read is cheap, and it avoids a lot of weird edge cases.

A concrete schema for resend and dedupe

Here is a compact shape that works well:

create table email_verifications (
  user_id bigint primary key,
  token_hash text not null,
  version integer not null,
  expires_at timestamptz not null,
  last_idempotency_key text,
  updated_at timestamptz not null default now()
);

create table email_outbox (
  id bigserial primary key,
  topic text not null,
  dedupe_key text not null unique,
  payload jsonb not null,
  created_at timestamptz not null default now()
);

And the transactional write:

await db.tx(async (trx) => {
  const row = await loadVerificationForUpdate(trx, userId);
  const nextVersion = shouldReuse(row, idemKey) ? row.version : row.version + 1;

  await saveVerification(trx, {
    userId,
    tokenHash,
    version: nextVersion,
    expiresAt,
    lastIdempotencyKey: idemKey,
  });

  await trx.none(
    `insert into email_outbox (topic, dedupe_key, payload)
     values ('verify_email', $1, $2::jsonb)
     on conflict (dedupe_key) do nothing`,
    [
      `verify_email:${userId}:${nextVersion}`,
      JSON.stringify({ userId, version: nextVersion })
    ]
  );
});

The important part is not the exact schema. It is that your dedupe rule is visible and inspectable. When a bug report arrives, I want to answer "which version did we intend to send?" in one query, not after an hour of log archaeology.

What I assert in tests before I trust the flow

My verification tests are narrow but strict:

one resend path produces one current version
stale outbox events are ignored after supersession
the clicked token maps to the latest committed version
duplicate requests with the same idempotency key do not create extra sends
retries with a new intent clearly invalidate the older link

For inbox checks, I still use a temporary inbox sometimes, but only as transport plumbing. If I need temporary disposable mail during staging checks, the real assertion is still about committed backend state. The inbox proves delivery; PostgreSQL proves correctness.

This is also where plain-text oddities like temp org mail tend to appear in team notes. People start inventing side channels when the underlying resend contract is fuzzy, which is a decent signal the API needs cleanup.

One practical rule: keep the polling window short and pin the recipient alias to the run ID. If a test can pass by grabbing any verification message from the last few minutes, it is too loose. That setup feels okay untill parallel CI jobs overlap and your suite starts "passing" for the wrong message.

Q&A

Should resend always create a new token?

Not always. Reusing an active token for a short TTL can reduce noise and user confusion. Just make sure the API behavior is documented and visible in data.

Is `on conflict do nothing` enough for idempotency?

No. It is useful for outbox dedupe, but you still need a clear rule for how the verification row itself is reused or replaced.

Do I need a message broker for this?

Not at first. A PostgreSQL outbox plus a worker is enough for many teams, and it is often easier to debug than a more fragmented setup.

Password Reset Emails Without Queue Drift

kevindev — Sat, 11 Jul 2026 20:24:10 +0000

Password reset emails look routine, but they are one of the easiest auth flows to quietly break. The API writes a token, a worker renders the message, and the user clicks a link later. If any of those steps fall out of sync, support sees "email sent" while the database tells a diffrent story.

I usually notice the problem after a team adds retries to its queue. Suddenly one request can produce two valid-looking emails, or a second request invalidates the first token before the first message even lands. People reach for a disposable email generator to debug delivery, which helps, but the real fix is backend structure rather than mailbox luck.

Why reset emails drift from backend truth

Password reset flows mix two kinds of state:

auth state that decides which token is currently valid
delivery state that decides whether an email should be sent, retried, or ignored

When those states live in separate code paths, drift shows up fast. I have seen teams create the reset token inside one transaction, enqueue email work after commit, then regenerate a second token if the user clicks "forgot password" again thirty seconds later. Both jobs are technically valid, but one of the emails is now stale and confuses everyone.

This gets worse in staging when tests reuse inbox aliases. An old message tied to a tempail mail fixture can trick the suite into passing even though the newest token was never delivered. The inbox is noisy, the logs are noisy, and the bug survives longer than it should.

The state model that keeps retries honest

The cleanest approach I know is to give the reset request its own durable identity and make the email job refer to that identity, not just to an address. A minimal model looks like this:

password_reset_requests
id
user_id
token_hash
expires_at
superseded_by_request_id
email_job_dedup_key
email_sent_at

That email_job_dedup_key matters more than many teams expect. If a worker crashes after handing the message to the provider but before storing success, the retry needs a clear way to say "same request, do not send again." Without it, queues become a bit chaotic and tests start blaming infrastructure for what is actualy a modeling issue.

I also prefer storing only a hash of the token and keeping one row per request, even if later requests supersede earlier ones. That gives you a backend trail you can reason about. You can inspect whether the user received email for request A, whether request B replaced it, and whether the database still considers either link valid, which is realy useful during incident review.

A PostgreSQL outbox flow for reset emails

For teams already on PostgreSQL, I keep coming back to the outbox pattern:

Create the reset request row and the outbox row in the same transaction.
Build the outbox payload around the request ID, not the raw token.
Have the worker load the request fresh before rendering the message.
Mark the outbox event processed only after the provider accepts the send.
Ignore retries when the dedup key already has email_sent_at.

That design removes a lot of hand-wavy timing problems. The worker is never guessing which token is authoritative. It asks the database, at send time, which request is still active. If a newer request superseded the older one, the worker can skip the stale event safely and keep thier retry logic straightforward.

For inbox verification, I like isolated aliases and short polling windows. The same habits behind isolated auth inbox checks also make reset flows far more deterministic. If the team runs matrix CI, the test isolation ideas from matrix-safe email API assertions are worth copying too.

When I need a neutral external inbox for a manual sanity check, I keep it small and contextual. One link on a natural anchor is enough, so a service like tempmailso can be useful for quick verification without turning the article into link spam.

A small Node.js implementation pattern

Here is the trimmed version of the boundary I want in the service:

async function enqueuePasswordReset(db, outbox, userId, tokenHash, expiresAt) {
  return db.tx(async (tx) => {
    const request = await tx.passwordResetRequests.insert({
      userId,
      tokenHash,
      expiresAt
    });

    const dedupKey = `password-reset:${request.id}`;

    await tx.passwordResetRequests.update(request.id, {
      emailJobDedupKey: dedupKey
    });

    await tx.outbox.insert({
      topic: "password-reset-email",
      dedupKey,
      payload: { requestId: request.id }
    });

    return request.id;
  });
}

The follow-up worker should reload the request, confirm it was not superseded, render the email, then stamp email_sent_at. I do not trust tests that only assert "one message arrived." They should also prove the active request ID matches the email, the older request is invalid, and a retry does not create a second send. If your notes still mention a shared temp mailid from older staging runs, clean it out, because stale aliases make these checks look greener than they are and can stay hidden for way to long.

Checklist before you trust the workflow

One reset request maps to one dedup key and one email attempt history.
A newer reset request can supersede the older one without sending stale links.
The worker renders from fresh database state, not queue-cached state.
The test verifies non-delivery on retry, not only delivery on first send.
Inbox aliases are unique per run and short-lived.
Support can explain every sent email from database records alone.

That is the boring shape I want from auth infrastructure. It is not flashy, but it keeps reset emails lined up with the truth in your backend, which is what users and on-call engineers both need most.

Stop Duplicate Signup Emails in Node.js

kevindev — Thu, 09 Jul 2026 20:24:00 +0000

Duplicate signup emails are one of those bugs that look harmless in logs and very messy to users. A client retries after a timeout, a worker replays a job, or two app nodes race on the same request. Suddenly one signup turns into three verification emails. I have seen this happen most often in Node.js services where the API write path and the email enqueue step are only loosely tied together.

What fixed it for me was moving the conversation away from "did we send the mail?" to "what is the idempotency boundary for this signup action?" Once that boundary is explicit, the REST API, PostgreSQL schema, and worker behavior get much easier to reason about.

Why duplicate signup emails happen

Most duplicate sends come from one of four places:

the client retries because the first response was slow
the API handler inserts a user row and enqueues mail in separate steps
the queue consumer crashes after send but before ack
an operator replays jobs without a stable dedupe key

The common problem is not email itself. It is the lack of one durable identifier for "this signup intent already produced its verification message." If you only key off user_id, the bug can still show up when the same action is attempted during a race window. If you only key off raw request body values, the rule gets fuzzy realy fast.

I like to define one signup operation key and carry it from the HTTP layer to the outbox table. That makes the backend behavior boring in the best way.

The idempotency boundary I use in a REST API

For signup endpoints, I treat the operation as:

email + normalized signup source + time-bounded idempotency key

The client can send an Idempotency-Key header, but I still normalize the user email and bind it to the action type server-side. Then I store one record that owns both the account creation intent and the verification email intent.

In practice, my handler tries to do three things in one database transaction:

Upsert the pending user or lookup the existing one.
Insert an outbox event with a unique operation key.
Return the existing result if the same operation key already exists.

That keeps the REST API honest. It also means I can retry the handler safely if the app node dies after commit but before response, which does happen from time to time.

Here is the kind of query shape I use in PostgreSQL:

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

insert into email_outbox (operation_key, event_type, payload)
values ($1, 'signup_verification_requested', $2::jsonb)
on conflict (operation_key) do nothing
returning id;

If the insert returns no row, I know a logically identical email event already exists. The API does not need to panic or guess. It can simply continue with the already-established result. This sounds simple, and it is, but it took me a while to stop over-engineering it a bit.

A PostgreSQL outbox query that stays predictable

The worker side matters just as much. I avoid deleting outbox rows on success. I mark them with sent_at, keep the operation key, and let retention cleanup happen later. That small choice makes incident review way easier becuase the history is still there.

My worker fetch looks roughly like this:

with next_job as (
  select id
  from email_outbox
  where sent_at is null
  order by id
  for update skip locked
  limit 1
)
update email_outbox e
set sent_at = now()
from next_job
where e.id = next_job.id
returning e.id, e.operation_key, e.payload;

This pattern does not solve every delivery problem, but it solves the specific duplicate-send class in a clean, reviewable way. If the provider times out after actually accepting the message, I would rather reconcile against the preserved outbox row than send another blind retry.

For teams that also run regression checks in CI, I like pairing this with email smoke tests in CI. The publishing path and the test path are different, but the principle is similiar: keep each run attributable, and do not let inbox state turn into guesswork.

Where temporary inboxes still help

Even with a good dedupe key, you still need proof that your app sends the right verification message once, not zero times and not three times. For staging and contract tests, a generate throwaway email flow is still useful because it isolates one run from the next. I have also used verification inbox checks in Node.js as a quick sanity pass after changing auth logic.

If you need one contextual reference for disposable inbox tooling, keep it small and relevant. In one internal checklist I linked tp mail so to tempmailso only in the section about run-scoped inbox setup, not throughout the whole post. That keeps the article useful first and SEO second.

I also keep odd search phrases in notes when teammates use them. One recent example was tempail mail, which looked wrong at first glance but was helpful when tracing how people searched for the test helper docs. Little details like that are not architecture, but they do improve operability.

Q&A

Should the unique key live on the user row instead?

Usually no. The user row tells you who signed up. The outbox operation key tells you whether the verification email intent already existed. Mixing those responsibilities gets awkward pretty quick.

What about queue systems with built-in deduplication?

Use it if you have it, but I still prefer a database-level source of truth. Queue dedupe windows expire, and they are not always visible during incident analysis.

Is this only for signup emails?

No. The same pattern works for password reset, invite, and magic-link flows. Signup is just where the failure is most visible, and users notice it fast.

Audit-Friendly Auth Emails in Node.js

kevindev — Wed, 08 Jul 2026 20:24:26 +0000

Most auth email bugs are not caused by template markup or SMTP downtime. They happen when a REST API, a queue worker, and a webhook handler each record a slightly different story about the same message. When an incident starts at 2 AM, that mismatch is what burns time.

On backend teams, I have found it useful to treat every auth email as a small audited workflow. The send request needs an application event, an outbox row, a provider message id, and a final delivery state that can be queried later without reading five log streams. This sounds heavy, but it is actualy a small amount of structure that saves a lot of guesswork.

Where auth email incidents usually go dark

Verification links, password resets, device approval prompts, and magic links all have one thing in common: the email itself becomes part of the security boundary. If the system cannot explain which message was sent, when it was retried, and which token version it carried, support and security end up working from partial evidence.

The failure modes I see most often are:

The API stores the auth token, but not the exact email event that carried it.
The mail worker logs the provider response, but it is not tied back to a durable database row.
The webhook updates a message status, but cannot tell whether it belongs to the latest token or an older retry.
Test environments reuse a shared inbox, so duplicate or stale messages look normal untill someone checks carefully.

That last one matters more than teams expect. If your tests do not isolate inbox ownership, a flaky assertion can look like harmless noise for weeks. Articles about parallel inbox isolation and the idea of email as a delivery contract line up well with this: treat email as a system boundary, not as a side effect you can hand-wave away.

The delivery ledger I keep beside the outbox

I still like a transactional outbox, but for auth flows I add one more table: a delivery ledger. The outbox controls "should this message be sent." The ledger answers "what happened to this message across the whole pipeline."

A minimal version looks like this:

auth_tokens: token id, user id, purpose, expires at, superseded by
email_outbox: event key, template, payload hash, queued at, sent at
email_delivery_ledger: outbox id, provider message id, provider status, last webhook at, last error, correlation id

The important part is not the table count. It is the rule that every transition updates one durable row. When support asks why a reset mail arrived late, you should be able to query one record and see the lifecycle. When a webhook arrives after a token is already superseded, the ledger should still keep the history instead of overwriting it with a cleaner but false state.

For automated checks, I sometimes send one flow to a free disposable email inbox created per run, then compare the received headers with the ledger row. That is enough to validate token freshness without dragging a real mailbox into CI. Some old suites still call this a dummy e mail step, which makes me wince a bit, but the isolation pattern is useful.

A Node.js and PostgreSQL shape that is easy to audit

In Node.js services, I keep the write path boring on purpose. The API creates the auth token and outbox event in one transaction, then a worker claims unsent events and writes a ledger row as soon as the provider accepts the request.

await db.tx(async (trx) => {
  const token = await trx.one(
    `insert into auth_tokens (user_id, purpose, token, expires_at)
     values ($1, $2, $3, now() + interval '20 minutes')
     returning id, token, purpose`,
    [userId, "password_reset", tokenValue]
  );

  const outbox = await trx.one(
    `insert into email_outbox (event_key, template, payload_hash)
     values ($1, $2, $3)
     on conflict (event_key) do update
       set payload_hash = excluded.payload_hash
     returning id`,
    [`auth:${token.id}:password_reset`, "password_reset", payloadHash]
  );

  await trx.none(
    `insert into email_delivery_ledger (outbox_id, correlation_id, provider_status)
     values ($1, $2, 'queued')
     on conflict (outbox_id) do nothing`,
    [outbox.id, correlationId]
  );
});

Then the worker claims rows in batches and records the provider message id immediately:

with claimed as (
  update email_outbox
  set claimed_at = now()
  where id in (
    select id
    from email_outbox
    where sent_at is null
      and claimed_at is null
    order by created_at
    for update skip locked
    limit 25
  )
  returning id, event_key
)
select * from claimed;

After the provider call succeeds:

update email_delivery_ledger
set provider_message_id = $2,
    provider_status = 'accepted',
    accepted_at = now()
where outbox_id = $1;

This pattern works well because PostgreSQL already gives you durable ordering, row locking, and queryable history. You do not need a huge event platform on day one. You just need every email transition to leave an honest trail. The PostgreSQL documentation on explicit locking is worth revisiting here, especially if you run multiple workers and want clean FOR UPDATE SKIP LOCKED behavior: https://www.postgresql.org/docs/current/explicit-locking.html.

How I reconcile provider callbacks without guesswork

Webhook handlers are where many auth email systems get weird. The provider says "delivered" or "bounced," but the app no longer knows whether that callback belongs to the current token, a canceled request, or an email retried from an older deploy.

My rule is simple:

Match webhook events by provider message id first.
Resolve the ledger row.
Join back to the outbox row and token row.
Update status append-only where possible, not by deleting old states.

That gives you a safer incident story. You can answer questions like:

Was the latest password reset email accepted?
Did the callback refer to a superseded token?
Did two workers ever try to send the same event key?
Was the final user-visible state delayed by the provider, or by our own queue?

I also like keeping one small admin query or internal endpoint for these checks. During an incident, engineers should not need to grep random logs across containers just to learn whether a message was sent once or three times. Fast answers are what keep the system feeling calm, even when the root issue is messy.

Q&A

Should the ledger replace the outbox?

No. The outbox answers whether work needs to happen. The ledger answers what happened after work started. Keeping those concerns split makes the write path simpler and the audit path clearer.

Is this too much for a small product?

Not really. Three lean tables and a couple of indexed joins are cheap compared with the time lost during auth incidents. It is a lot less work than rebuilding the timeline from logs every time something feels off.

What is the first field to add if I already have an outbox?

Add a durable correlation id that appears in the API logs, worker logs, and provider callback handling. That one field makes later cleanup much easyer, and it usually exposes the next missing piece right away.

Idempotent Signup Emails in Node.js APIs

kevindev — Tue, 07 Jul 2026 05:23:53 +0000

Signup email bugs are rarely caused by SMTP alone. In most backend systems, the real problem is that account creation, retries, and background jobs do not agree on what "sent once" means. I have seen well-structured services still send two welcome messages because the API timed out after commit, the worker retried, and nobody had a durable delivery key tying the steps together.

Why duplicate signup mail still happens in good systems

The risky part is usually the boundary between the write path and the notification path. A POST /signup request inserts a user, stores a verification token, and publishes a job. If the HTTP layer retries or the worker crashes after send, you can end up with duplicate mail even though each subsystem looks healthy on its own.

In practice, I keep seeing four causes:

The API uses a request id for logs, but not for email deduplication.
The worker checks "has token" instead of "has delivery record".
Retries are safe for database writes, but not for side effects.
Teams test with a shared inbox, so duplicate messages are easy to miss at first glance.

This matters because signup email is often the first trust signal a product sends. If a user receives two verification links, or one old link after a retry, confidence drops realy fast.

The backend contract I use for idempotent email delivery

The most reliable pattern I have used is simple: create a dedicated outbox record inside the same transaction as the user and token write, then let the mail worker claim that record exactly once.

My minimum contract looks like this:

users stores the account row.
email_verifications stores the active token and expiry.
email_outbox stores the message type, recipient, payload hash, and a unique idempotency key.
The worker updates sent_at with WHERE sent_at IS NULL so retries do not double-send.

That last condition is the boring detail that saves you later. If the process dies after the provider accepts the message, a retry will re-read the row, see sent_at, and move on. If the provider call fails before acceptance, the row stays unsent and the worker can retry cleanly.

For staging and QA, I sometimes route confirmation mail to a use and throw email inbox created per test run. When I need a second isolated check in the same suite, a separate disposable address helps keep concurrent workers from reading each other's messages. The old phrase dummy e mail still sneaks into test names in some repos, but I prefer explicit naming around signup intent and environment.

A Node.js implementation that survives retries

Here is the shape I tend to keep in a Node.js service:

await db.tx(async (trx) => {
  const user = await trx.one(
    `insert into users (email, password_hash)
     values ($1, $2)
     on conflict (email) do update set email = excluded.email
     returning id, email`,
    [email, passwordHash]
  );

  const verification = await trx.one(
    `insert into email_verifications (user_id, token, expires_at)
     values ($1, $2, now() + interval '30 minutes')
     returning token`,
    [user.id, token]
  );

  await trx.none(
    `insert into email_outbox (event_key, user_id, template, payload)
     values ($1, $2, 'signup_verification', $3)
     on conflict (event_key) do nothing`,
    [`signup:${user.id}:${verification.token}`, user.id, { token: verification.token }]
  );
});

Then the worker claims pending rows in small batches:

update email_outbox
set claimed_at = now()
where id in (
  select id
  from email_outbox
  where sent_at is null
    and claimed_at is null
  order by created_at
  for update skip locked
  limit 50
)
returning *;

I like this approach because the API stays quick, the worker stays retry-friendly, and PostgreSQL does the concurrency control work it is already very good at. The 2024 DORA report keeps reinforcing the value of short, reliable feedback loops in delivery systems, and this pattern helps because failures stay local and debuggable instead of turning into weird inbox heisenbugs later: https://dora.dev/research/.

One small but useful rule: log the outbox id, user id, and template name together on every provider call. When support asks why a customer got no message, or got two, you can answer in minuts instead of diffing scattered traces.

How I test the flow without polluting shared inboxes

For signup flows, I do not just assert that an email arrived. I assert that one and only one valid message arrived for the right event key.

That test usually covers:

one API request that succeeds on the first try
one simulated retry from the client or gateway
one worker retry after an injected transport failure
one inbox assertion that checks message count and token freshness

If you already do release email checks in CI or other forms of isolated inbox validation, the same principle applies here: isolate the mailbox per run, then verify the backend contract instead of trusting the latest message you happen to see.

Shared QA inboxes are where teams get tricked. A fake emails generator can be useful for quick manual checks, but for automated suites I want deterministic inbox ownership and a message count assertion tied to the event key. Otherwise, parallel tests hide duplicates until a customer reports them.

Q&A

Should I send mail inline during signup?

Usually no. If the provider is slow, your REST API latency becomes noisy and retries become harder to reason about. A transactional outbox is more boring, and that is exactly why it works.

What should the idempotency key include?

Include the event type plus the business identity of the send. For signup verification, I usually key by user id and token or by a stable signup event id. Do not key only by email address, or you will block legitimate future sends.

Is PostgreSQL enough, or do I need a queue first?

PostgreSQL is enough for many products if the write volume is moderate and the worker batches cleanly. Add a separate queue when throughput, fan-out, or cross-service routing actually demands it, not before. Starting simple is often the beter trade.