ValidReach Technical Architecture: Edge Pre-Checks, Async Batch Queues, and Scoped Workspaces

When engineering teams evaluate an email verification service, marketing superlatives matter far less than how the pipeline handles edge cases: malformed inputs, transient DNS failures, multi-hundred-thousand-row CSV uploads, webhook retries, and shared team budgets.

This article documents the concrete technical architecture behind ValidReach and how each layer is designed to keep verification predictable, auditable, and safe to integrate into production codebases.

1. Edge-first pre-checks and deterministic status taxonomy

Every request to POST /api/v1/verify/single or POST /api/v1/verify/bulk enters a Cloudflare Worker at the edge before any external network probe occurs:

1. RFC 5321 / RFC 5322 syntax parsing: Local-part quoting, domain label rules, and length constraints are checked deterministically.
2. Disposable domain and role-account detection: High-churn disposable providers can be queried for free via GET /api/v1/verify/disposable without spending verification credits, and role aliases (such as support@ or billing@) are flagged explicitly.
3. DNS and MX verification: Domain MX records and Null MX (RFC 7505) declarations are resolved before attempting mail-server checks.
4. Seven-status vocabulary: Every address resolves to one of seven documented statuses (valid, invalid, catchall, disposable, role, unknown, or risky) paired with a structured reason code and is_deliverable boolean.

Critically, when a receiving mail server greylists or times out, ValidReach returns unknown with retryable: true and charges zero credits, rather than guessing.

2. Asynchronous file jobs with row-level traceability

Uploading a large CSV or .xlsx workbook through a synchronous HTTP request inevitably hits gateway timeouts. ValidReach separates file ingestion from verification execution through /api/v1/verify/file:

• RFC 4180 CSV, TSV, and binary .xlsx parsing: Uploads are stored in Cloudflare R2 with zip-bomb safeguards and automatic 30-day source-file expiry (/data-retention).
• Source row preservation: Every extracted address retains its source_row index. When downloading results via GET /api/v1/verify/file/{task_id}/results, passing include_original=true streams the original spreadsheet columns (orig_<header>) alongside the verification columns directly from D1 and R2 without truncating at a single UI page.
• Conditional credit state machine: Batch rows transition atomically from reserved to settled or released in SQLite/D1 so queue redeliveries never double-charge a workspace.

3. Signed webhooks, OpenAPI 3.1 SDKs, and MCP OAuth

Modern verification pipelines rarely run in isolation. ValidReach ships four developer integration surfaces out of the box:

• HMAC-SHA256 webhooks: Register HTTPS endpoints on /api/v1/webhooks or /settings/webhooks for file.completed and file.failed events, signed with a timestamped X-ValidReach-Signature header.
• Kiota-generated SDKs from OpenAPI 3.1: TypeScript, Python, Go, PHP, and Java clients are generated directly from /openapi.json, and the server natively decompresses gzip and deflate request bodies sent by strongly typed SDK adapters.
• CLI and n8n community node: The zero-dependency @validreach/cli maps HTTP 401/402/429 responses to distinct POSIX exit codes for CI/CD scripts, while n8n-nodes-validreach wraps single, bulk, disposable, and credit checks for visual workflows.
• MCP Server with OAuth 2.1 + PKCE: AI coding assistants and agents can authenticate via dynamic client registration (/api/auth/mcp/register) or API keys at /api/mcp (/docs/ai-guides/mcp).

4. Workspace isolation and team budget caps

Agencies and multi-product companies often share a single billing account across several environments or client teams. ValidReach scopes every API key, batch job, and verification record to a workspace and optional team (/settings/workspace, /settings/teams):

• Scoped API keys: A key bound to a team draws from the workspace owner’s credit balance up to the team’s configured credit cap (team_budget_exceeded), preventing a runaway staging script from exhausting production credits.
• Audit trail: Membership changes, team budget updates, API key scope changes, and ownership transfers are recorded in an append-only workspace audit log.

Sources

• ValidReach Verification Methods and Pipeline Order (accessed 2026-11-04)
• ValidReach OpenAPI 3.1 Specification (accessed 2026-11-04)
• ValidReach Data Retention and Subprocessors (accessed 2026-11-04)
• IETF RFC 5321 — Simple Mail Transfer Protocol (accessed 2026-11-04)