Queue Verification Email Without False Success

The verification prompt in AdzByte App needed to tell the user what had actually happened to their email. That sounds like a copy change, but the useful fix sat further down: the queue write, transaction, resend protection, and failure handling all had to agree.

In my October account-lifecycle change, I added a dedicated action for verification dispatch and tests that run a worker against a local SMTP sink. The interesting part is where the action decides it can truthfully return “queued.” That point comes before mailbox delivery, but after a durable database operation.

Choose the queue arrangement before the transaction

The action starts by requiring the database queue to use the application’s default database connection. It throws if that arrangement isn’t true. This is a deliberate restriction in this implementation, and it’s worth reading before copying the dispatch call.

Inside the transaction, the action sends the notification on the database queue with beforeCommit(). That can look surprising if you’re used to recommending after-commit dispatch everywhere. Here the queued row is written through the same database connection as the surrounding transaction. The transaction determines whether that queue write survives.

An external broker changes the reasoning. Sending a message to a separate service before committing wouldn’t give the application the same rollback behavior. The configuration check makes the assumption visible instead of leaving it in a comment that someone might miss when changing queue drivers.

For another application, I’d first decide what must be committed together and which connection performs each write. The method name alone doesn’t tell you whether a dispatch arrangement is safe.

Recheck the user inside the operation

The action locks and reloads the user, checks access to the current panel, and checks whether the address is already verified. It doesn’t rely entirely on the object passed from the page. Those are decisions about the state at dispatch time.

The notification URL comes from the selected panel. Staff and customer pages share the dispatch action, but the resulting link still points at the intended verification route. That keeps panel-specific URL generation out of the prompt’s presentation code.

This separation makes the tests easier to read too. The page asks for verification; the action decides whether the request is eligible and whether a job can be queued. A test can exercise those decisions without pretending that displaying a success message proves anything about the queue.

Keep resend protection shared across entry points

A verification page can be refreshed. The resend action can be clicked. A user with both roles can open the other panel. Protecting only the visible button would leave the other paths able to request more work.

The implementation uses a short cache lock keyed to the user and a cooldown keyed to the user and a hash of the verification address. The address matters because a later mailbox change shouldn’t blindly inherit a cooldown for an unrelated destination.

The action returns separate outcomes for busy, recent, already verified, and newly queued requests. The prompt turns those into appropriate guidance. A busy request doesn’t become a claimed enqueue, while a recent committed request can tell the user to wait.

These are bounded protections with a lock lifetime and cache dependencies. I wouldn’t describe them as a universal exactly-once email guarantee. Their useful purpose is to coordinate the known request paths and make their results understandable.

Start the cooldown after the queue write commits

The cooldown is written only after the database transaction returns successfully. If enqueueing fails, the user shouldn’t be forced to wait through a cooldown for work that doesn’t exist. The failed-enqueue test makes that expectation concrete.

There’s another less obvious case: the queue write succeeds, then cache cleanup fails. At that point, reporting “could not queue” would give the user the wrong recovery instruction. They might request another email even though the first job is already committed.

The action catches failures while storing the cooldown or releasing the lock and records a warning. Its warning helper also prevents a logging failure from replacing the committed result. That doesn’t make the cache failure harmless, but it preserves the distinction between failed dispatch and failed housekeeping.

A useful review question for other workflows is this: after the main write succeeds, which later exceptions can still turn the response into a failure? An audit message, lock release, or optional cache update deserves its own failure policy.

Follow the email through a real worker

The regression suite checks queue rows, then goes further. It starts a worker and a local SMTP sink, captures the outgoing message, extracts the generated link, and follows it. That crosses the serialization and worker boundary that a notification fake would skip.

The link tests cover tampering, expiry, the wrong signed-in user, and successful verification by the intended user. Separate tests cover refresh duplication, shared cooldowns across panels, a held lock, enqueue failure followed by retry, and lock-release failure after a committed enqueue.

Those are synthetic tests. They establish behavior through the application’s test worker and SMTP capture, not delivery into a real customer’s inbox. Spam filtering, provider acceptance, and mailbox placement need separate evidence.

Make the message match the completed step

The prompt says the email has been queued and explains that delivery can take time. When enqueueing fails, it says so and offers a retry. Neither message needs to claim more than the action knows.

That was the main lesson from this fix: define the successful step precisely, then keep transactions, cooldowns, cleanup, and copy aligned with it. Once “queued” means a committed queue record, the failure tests can check something much more useful than whether the page displayed a reassuring sentence.