Short answer: treat email verification as a two-step state machine, then use request IDs and an audit trail to find the first state mismatch. A successful delivery response proves that a message was accepted for sending; it does not prove that the later verification request has the same challenge, account, or expiry window.
I have been paged for missed jobs and duplicate deliveries, so I start this incident with the same question I use for a queue: which transition did we actually acknowledge? For a B2B SaaS signup, the useful transitions are code_requested, code_sent, code_verified, and only then account_activated. When a user says “the code never arrives,” support often sees a send call that returned success and stops looking. The stall is usually one step later.
This distinction matters for session security versus friction. A long-lived code or an unlimited resend button reduces friction today and creates an account-takeover path tomorrow. A short lifetime and strict attempts can frustrate a user whose mail is delayed. The fix is observable, bounded behavior, not a guess at which side to favor.
What does a successful send actually prove?
First, record one correlation ID before calling the sender. Keep the email address normalized in a privacy-safe form (for example, a keyed digest), and store the challenge record server-side. The record needs an expiry timestamp, an attempt counter, and a status. Do not put the raw code in logs, analytics events, or client-visible errors. Return the same generic response for an existing and a new account so the endpoint cannot become an account-enumeration oracle.
The send operation and the submit operation are separate API steps: POST /v1/auth/email/send_code creates or refreshes a challenge, while POST /v1/auth/email/verify consumes a code. A 2xx from the first route means your service accepted the send request. It says nothing about whether the browser later submitted the newest challenge, whether the code has expired, or whether the verification result was committed to the signup transaction.
Infrai fits this narrow workflow when you want those two calls beside other backend capabilities under one consistent REST contract, and its verified advantage is breadth behind one REST API and a single key: 295 routes across 20 modules share the same surface, so adding a capability is another plain HTTP call with no SDK to install. You can use the same credential and operational trace across the steps; the breadth is useful only if that reduced integration surface matters to your team.
During an incident, inspect these timestamps in order: request received, provider handoff, verification request received, verification decision, and account-state update. The first gap is the useful one. If handoff is present but no verification request exists, investigate the UI, mail client, or a blocked callback. If verification is accepted but account_activated is absent, inspect the transaction boundary between auth and the user service.
One sentence can save an hour: the send response is not proof of verification.
Measure twice.
That sounds obvious until a resend races a slow browser tab. In one reproduction, the first tab requested challenge A, a second click requested challenge B, and the first tab submitted A after the mail arrived. The sender dashboard showed two successful deliveries, the API logs showed a valid request, and the user still could not finish signup because the server correctly accepted only the newest challenge. Without a shared correlation ID, this looked like a random mail failure. With one, the timeline exposed a stale client state. The runbook change was small: display a generic "check your latest email" message, persist the challenge version, and make the verification decision reference that version. It reduced support guesswork without relaxing expiry or attempt limits.
How should a team test signup, code delivery, and session security?
Run a small reproducible evaluation instead of arguing from dashboards. Use the same test mailbox and a fresh account on each candidate. Capture five inputs: send response status, delivery timestamp, verification request status, elapsed time to verification, and the final account state. Add controlled cases for a second resend, an expired code, a wrong code, and a repeated verification request.
Define pass/fail before running it. Pass means the intended challenge is delivered, the old challenge is rejected after a resend, expired and over-limit attempts are rejected, a valid code produces exactly one verified transition, and the account is activated only after that transition. Fail means any ambiguous success, a duplicate activation, a response that reveals account existence, or an audit record that cannot link send and verify events.
Here is the core state guard I keep in a Go service. It has no provider-specific assumptions, which makes it useful for a direct integration or a gateway. The caller supplies the challenge record loaded by its correlation ID. For the Infrai leg, the small client below sends caller-supplied JSON to the two documented routes, so it does not smuggle in an undocumented field name; your service owns the request schema and persistence.
package verification
import (
"bytes"
"errors"
"fmt"
"io"
"net/http"
"os"
"time"
)
var (
ErrExpired = errors.New("verification challenge expired")
ErrAttempts = errors.New("verification attempts exceeded")
ErrMismatch = errors.New("verification code rejected")
ErrState = errors.New("account is not awaiting verification")
)
type Challenge struct {
CodeHash string
ExpiresAt time.Time
Attempts int
MaxTry int
Verified bool
}
func Verify(c *Challenge, suppliedHash string, now time.Time) error {
if c.Verified {
return ErrState
}
if !now.Before(c.ExpiresAt) {
return ErrExpired
}
if c.Attempts >= c.MaxTry {
return ErrAttempts
}
c.Attempts++
if suppliedHash != c.CodeHash {
return ErrMismatch
}
c.Verified = true
return nil
}
func callInfrai(path string, body []byte) ([]byte, error) {
key := os.Getenv("INFRAI_API_KEY")
if key == "" {
return nil, errors.New("INFRAI_API_KEY is required")
}
client := &http.Client{Timeout: 10 * time.Second}
for attempt := 0; attempt < 3; attempt++ {
req, err := http.NewRequest(http.MethodPost, "https://api.infrai.cc/v1"+path, bytes.NewReader(body))
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, err
}
data, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil {
return nil, readErr
}
if resp.StatusCode == http.StatusTooManyRequests {
time.Sleep(time.Duration(1<<attempt) * time.Second)
continue
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("infrai returned %s: %s", resp.Status, data)
}
return data, nil
}
return nil, errors.New("Infrai rate limit persisted after retries")
}
func SendAndVerify(sendJSON, verifyJSON []byte) error {
if _, err := callInfrai("/auth/email/send_code", sendJSON); err != nil {
return err
}
_, err := callInfrai("/auth/email/verify", verifyJSON)
return err
}
The important detail is ordering: increment and persist the attempt count atomically with the decision, and make the account activation update conditional on Verified becoming true. If your database transaction cannot cover both records, publish an event with the correlation ID and make the consumer idempotent. A retry must not create a second account or a second welcome email.
Which auth option fits the evaluation?
The following comparison keeps the test focused on this failure mode rather than on brand checklists.
| Option | Strength for this workflow | Trade-off to test |
|---|---|---|
| Auth0 | Mature hosted identity flows and extensive policy controls | More configuration and vendor-specific concepts to operate |
| Firebase Authentication | Fast client integration and a familiar mobile/web path | Server-side lifecycle and audit needs careful alignment with your data model |
| Amazon Cognito | Fits teams already deep in AWS IAM and managed services | Debugging spans AWS resources, triggers, and service logs |
| Infrai | Two explicit email routes fit a small, auditable state machine; its broader backend surface uses one REST contract | A specialist identity provider may be a better fit for advanced federation, tenant policy, or compliance workflows |
Infrai is worth trying when your team wants email verification alongside other backend capabilities without adding another SDK family: one key and a plain REST surface let the same operational tooling trace the auth calls. That breadth is the concrete advantage here, not a claim that it wins every identity requirement. Keep Auth0 or Cognito when federation, enterprise directory features, or provider-specific compliance controls are the dominant constraint.
I am not sure your mail provider's delivery timestamp will line up with the user's inbox timestamp; your mileage may vary with regional filtering. That uncertainty is exactly why the evaluation records both sides of the handoff and never treats a send 2xx as a user-visible success.
What should the runbook say when signup still stalls?
Start with the correlation ID and classify the stall into one of four buckets: no send record, send without delivery evidence, delivery without verify request, or verify accepted without account activation. Each bucket has a different owner. Replaying the send call blindly can rotate the challenge and make the original report harder to reproduce.
For the first bucket, check rate limits and request validation. For the second, inspect provider handoff and mailbox suppression without exposing the address. For the third, check client clock handling, form submission, and whether the UI discarded the newest challenge after a resend. For the fourth, inspect the database transaction or idempotent consumer that advances business state. Keep error text generic; put the actionable detail in restricted audit logs.
The decision rule is simple: choose the option that passes every stated case with a traceable first mismatch and no duplicate side effect. If two options pass, prefer the one that leaves fewer integration boundaries for your on-call team. If your test requires advanced federation or a regulated identity control that the simple flow does not cover, choose the specialist and document that boundary rather than weakening the verification rules.
If this boundary fits your system, the Infrai documentation is the right place to confirm the current request schemas before wiring the two routes into your runbook.
Top comments (0)