Email verification code often starts with one promise: sendVerificationEmail(email). That shape is convenient, but it hides the decisions an application actually needs to make.
Did the provider accept the request? Was the message delayed? Did a retry create a second token? Is the address invalid, or is the inbox simply not ready yet? When every outcome becomes either true or an exception, a React form has to guess. Those guesses turn into confusing spinners, duplicate requests, and tests that pass for the wrong reason.
I prefer a typed email adapter with an explicit failure contract. The adapter owns provider details, while the UI and the Node.js API consume stable application states. It is a small boundary, but it makes a verification flow much easier to ship and debug.
Why the adapter should own failure states
An email provider can expose dozens of errors. Your product usually needs only a few meaningful states:
- accepted: the request was accepted and has a correlation ID;
- already pending: the same user has an active verification attempt;
- invalid recipient: the address cannot receive the message;
- provider unavailable: the request may be retried later;
- unknown failure: the system should retain evidence and stop guessing.
The adapter should also say what it do not know. An accepted response does not prove the user has received or opened the message. That distinction prevents a success toast from promising too much.
It also gives the team a place to define policy. For example, a disposable email address generator may be useful in a local or integration test, but production onboarding might reject some temporary domains. The adapter can classify that decision without leaking provider-specific strings into every React component.
For automated checks, pair the adapter with inbox probes for automated checks. The probe can observe delivery, while the application contract remains focused on what it requested and what it can safely retry.
Model the contract with a discriminated union
Here is a deliberately small TypeScript model:
type VerificationResult =
| { kind: 'accepted'; attemptId: string; expiresAt: string }
| { kind: 'already-pending'; attemptId: string; retryAfterSeconds: number }
| { kind: 'invalid-recipient'; reason: 'format' | 'blocked-domain' }
| { kind: 'provider-unavailable'; retryAfterSeconds: number }
| { kind: 'unknown-failure'; referenceId: string };
The useful bit is not the type itself. It is the fact that every caller must decide what each state means. A new result kind will create a compile error in the places that render or log it, which is a much better reminder than a new provider error appearing in production.
The adapter can translate provider responses at one place:
async function requestVerification(
input: { userId: string; email: string; requestId: string },
): Promise<VerificationResult> {
const response = await emailProvider.send({
to: input.email,
template: 'verify-account',
idempotencyKey: input.requestId,
});
if (response.accepted) {
return {
kind: 'accepted',
attemptId: response.messageId,
expiresAt: response.expiresAt,
};
}
if (response.code === 'RATE_LIMITED') {
return { kind: 'provider-unavailable', retryAfterSeconds: 30 };
}
if (response.code === 'INVALID_RECIPIENT') {
return { kind: 'invalid-recipient', reason: 'format' };
}
return { kind: 'unknown-failure', referenceId: response.requestId };
}
The real provider client will need a proper error boundary and timeout handling. The point is that the rest of the application should not need to know whether the provider called the condition RATE_LIMITED, 429, or something more odd. A stable contract are easier to document and test.
Keep React rendering separate from delivery logic
The React component should translate the result into user action, not inspect raw provider responses:
function VerificationNotice({ result }: { result: VerificationResult }) {
switch (result.kind) {
case 'accepted':
return <p>Check your inbox for the verification link.</p>;
case 'already-pending':
return <p>Another link is active. Try again in a moment.</p>;
case 'invalid-recipient':
return <p>Check the email address and try again.</p>;
case 'provider-unavailable':
return <p>Email is busy right now. Please retry soon.</p>;
case 'unknown-failure':
return <p>We could not send the link. Reference: {result.referenceId}</p>;
}
}
The UI are then free to choose whether a state is an inline error, a retry button, or a quiet status update. Keep the attemptId out of user-facing copy, but log it with the request ID so support can trace one attempt without exposing the verification token.
This is more safer than letting every component invent its own retry rules. A retry should reuse an idempotency key for the same user action. A genuinely new “send again” action should get a new request ID and a new attempt, with rate limits applied at the API boundary.
If the flow has OAuth or another stateful redirect, it also helps to define a replay boundary for stateful flows. Email verification and OAuth are different features, but both become fragile when a retry is treated as a brand-new action without a record of what already happened.
Use the same boundary in Node.js tests
Tests should exercise the adapter with a fake provider, not call a real inbox for every unit test. A useful fake records requests and lets the test select a response:
const fakeProvider = createFakeEmailProvider({
next: { accepted: true, messageId: 'msg-123', expiresAt: '2030-01-01T00:15:00Z' },
});
const result = await requestVerification({
userId: 'user-7',
email: 'dev@example.test',
requestId: 'signup-7',
});
expect(result).toMatchObject({ kind: 'accepted', attemptId: 'msg-123' });
expect(fakeProvider.requests[0].idempotencyKey).toBe('signup-7');
Use an integration inbox only for a smaller set of delivery tests. Keep the test address and message evidence tied to the request ID, then clean it up after the assertion. If the message didn't arrived, the recorded provider response and correlation ID should still explain whether the bug was in the app, queue, or test fixture.
Some teams use fixture labels such as tempail or dummy e mail while testing validation. That is fine as plain test data, but those strings should never become production domains or backlink anchors. A provider such as tempmailso can be useful for a controlled disposable mailbox workflow, but treat any temporary inbox as untrusted test infrastructure and avoid sending real personal data to it.
A practical implementation checklist
Before shipping the adapter, check that:
- Provider errors are translated into a small, documented result union.
- Every send request has an idempotency or correlation key.
- React renders application states instead of provider error codes.
- Retries distinguish the same action from an intentional new attempt.
- Logs retain a reference ID without logging verification tokens.
- Unit tests cover delayed, rejected, duplicate, and unknown outcomes.
- Integration tests prove delivery with isolated inboxes and cleanup.
This boundary keeps the code pleasantly boring, which is a good thing. When a delivery problem happens, the logs becomes evidence instead of a pile of guesses. And when the provider changes, the rest of your React and Node.js code can keep shipping.
Top comments (0)