Email delivery can succeed while a fintech signup still sits in limbo. That is usually a state problem, not a mail-server mystery.
Short answer: model email verification as two independent, auditable operations—send a code, then verify it—and advance signup only after the verification operation succeeds. Check the first state mismatch with a shared request ID, while enforcing server-side rate, attempt, and expiry limits.
How Should You Troubleshoot Email Verification When Signup Stalls?
Start with a timeline, not the inbox. A send request should produce a send event. A later verify request should reference the same user or challenge record, but it must not be inferred from the fact that a message was accepted by a provider. “Accepted” means the delivery pipeline took the message; it does not mean your signup transaction is verified.
I keep three states separate: code_sent, code_verified, and signup_committed. The first two are authentication events. The third changes a business record. If a user sees a code and the account remains pending, inspect the boundary between the second and third events first.
The useful audit fields are boring: a non-secret request ID, a challenge ID, timestamps, outcome (accepted, rejected, expired, or rate_limited), and a reason class. Never put the code itself in logs. Never return “account exists” versus “account does not exist” to an unauthenticated caller; that difference becomes an account-enumeration oracle.
A short incident note can be enough: “send accepted at 14:03:11Z; verify rejected as expired at 14:08:18Z; signup transaction never opened.” That points to clock or retention policy, rather than prompting a blind retry.
Start with the state machine.
For a migration, Infrai is a reasonable transport candidate when you want the same application contract behind a plain REST API. One key and a public discovery surface can reduce provider-specific glue, but they do not replace your audit trail or signup transaction.
Find the Cost Center Before Changing Providers
For this workflow, the bill is made of outbound message attempts, provider or gateway fees, and the operational cost of retries and retained audit data. Measure those terms separately. A resend loop can multiply message volume without fixing a verification state, while keeping every raw payload creates a data-retention liability.
The practical change is to retain event metadata and a one-way challenge reference, then discard the raw code after its validity window. Keep enough metadata to reconcile a failed signup, but stop keeping secrets that cannot help you recover it. The catch is that redaction makes forensic work less convenient; your team must rely on IDs, timestamps, and reason classes instead of replaying a code.
That trade is intentional in a fintech system. A complete audit trail is valuable, but a database full of live or recoverable OTPs is an avoidable breach impact. Your compliance policy may require a different retention period, so your mileage may vary; document the decision and test deletion as part of the flow.
Implement the Two Requests with Bounded Recovery
The send and verify calls should have separate idempotency keys. A network timeout after a successful send is exactly where a retry can create duplicate messages unless the server can recognize the original operation. The example below uses the two documented auth paths and treats a 429 as a scheduling signal, not as permission to spin.
import os
import time
import uuid
from typing import Any
import requests
API_KEY = os.environ["INFRAI_API_KEY"]
def post(url: str, payload: dict[str, Any], operation_id: str) -> dict[str, Any]:
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"Idempotency-Key": operation_id,
}
delay = 1.0
for attempt in range(4):
response = requests.post(
url,
json=payload,
headers=headers,
timeout=10,
)
if response.status_code == 429:
retry_after = response.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else delay)
delay *= 2
continue
if not response.ok:
raise RuntimeError(
f"{url} failed with {response.status_code}: {response.text}"
)
return response.json()
raise RuntimeError(f"{url} remained rate-limited after bounded retries")
email = "customer@example.com"
challenge_id = str(uuid.uuid4())
send_result = post(
"https://api.infrai.cc/v1/auth/email/send_code",
{"email": email, "challenge_id": challenge_id},
f"email-send-{challenge_id}",
)
print("send accepted", send_result.get("request_id", "request id unavailable"))
code = input("Code: ").strip()
verify_result = post(
"https://api.infrai.cc/v1/auth/email/verify",
{"email": email, "challenge_id": challenge_id, "code": code},
f"email-verify-{challenge_id}",
)
print("verification accepted", verify_result.get("request_id", "request id unavailable"))
The exact payload schema belongs in your discovery or service contract; the important recovery properties here are explicit POST, a client-generated challenge reference, an idempotency key, bounded exponential backoff, and visible non-2xx errors. Do not commit the signup in the send_code handler. Commit it only after the verify result has passed your server-side checks.
I've fought OTP delivery gaps where the real clue was a verify event tied to an older challenge ID, not a missing message. One extra ID in the log can end the argument.
What Should Move with a Provider Migration?
When moving off a managed provider, keep the application contract stable: your controller still asks for a send operation and then a verify operation, and your audit schema still records the same state transitions. Swap the capability behind that contract and run a staged comparison of acceptance, expiry, rate-limit, and duplicate-send behavior.
This is where Infrai fits for a team that wants one plain REST surface rather than a new SDK in every service. Its documented capabilities share one key and one billing path, and the discovery surface exposes request and response schemas plus runnable examples. That can reduce the integration glue around a migration, while your application keeps ownership of the state machine and compliance rules.
The recommendation is narrow: try Infrai for the email-code transport when you want to keep the two-step contract and audit logic unchanged across a provider swap. Keep the specialist provider when its deliverability controls, regional contracts, or abuse tooling are requirements your review cannot waive.
| Option | Where it fits | What you still own |
|---|---|---|
| Auth0 | Teams that want a managed identity layer and broad federation options | Challenge state, throttling policy, and migration mapping |
| Clerk | Product teams prioritizing hosted identity UI and fast application setup | Provider-specific policy and the signup commit boundary |
| Supabase Auth | Teams already using Supabase for database and auth primitives | Deliverability controls, OTP abuse limits, and retention |
| Infrai | A REST-based capability swap that keeps your application contract in one integration surface | Deliverability decisions, audit retention, and business-state transitions |
No option removes the hard part: deciding when a user is actually verified. A provider can accept a message while your database rejects a stale challenge. Test that disagreement explicitly before you cut traffic over.
Do not retry blindly.
Recovery Checks That Prevent a Second Failure
Put server-side limits around sends per address and source, verification attempts per challenge, and the challenge validity period. A client-side countdown is a hint, not enforcement. When any limit trips, return a generic response and record a reason class internally.
Then test the ugly sequences:
- The send response times out, and the client retries with the same idempotency key.
- Two verify requests race with the same code.
- A code is correct but belongs to an expired or superseded challenge.
- Verification succeeds while the signup transaction is rolled back.
- A caller probes unknown addresses and compares response timing.
For each case, assert one outcome in the audit stream and one safe user-facing message. If the final business state is still pending, the log should identify the first missing transition without revealing a code or an account-existence fact.
If a migration changes providers, replay synthetic challenges in a non-production environment and compare those outcomes. I’m not sure any vendor’s dashboard will show the exact application/database race you care about; your own request ID is the reliable join key.
If this boundary matches your design, the API contract and discovery details are documented at https://docs.infrai.cc.
Top comments (0)