Setting up email validation in your Node.js backend

A practical guide to adding OhBounce.ai to an Express or Fastify API. Covers authentication, single-address validation, bulk list scrubbing, and error handling patterns.

Node.js is the most common backend environment our customers integrate from. Whether you're using Express, Fastify, or a serverless function, the pattern is the same. This guide covers setting up the integration correctly and handling the edge cases that trip up most implementations.

Environment setup

Store your OhBounce.ai API key in an environment variable — OHBOUNCE_API_KEY is a reasonable name. Never commit it to source control. In a serverless environment, use your platform's secret store (AWS Secrets Manager, Vercel Environment Variables, etc.).

Validating on user registration

In your registration handler, validate the email before creating the user record. Make a POST to the /api/v1/validate endpoint and inspect the status field. If status is INVALID or DISPOSABLE, return a 400 with a descriptive error message. For CATCH_ALL or UNKNOWN, you might choose to allow registration but flag the user for a follow-up verification email.

Rate limiting and caching

For high-traffic sign-up flows, consider caching validation results by domain for 24 hours. If you've validated fifty @gmail.com addresses today, the MX record hasn't changed — you can skip that lookup on subsequent calls. Cache at the domain level, not the full address level, to avoid privacy issues.

Validation adds ~100–200ms to your registration endpoint at p99. For most products this is imperceptible. If latency is critical, consider moving validation to an async post-registration step.

Bulk validation in a data pipeline

For processing uploaded CSV files or syncing from a CRM, use the bulk endpoint. Submit the job, store the jobId, and poll in a background worker or scheduled job until the status is COMPLETED. Stream results page by page and write them to your database. For very large jobs (100k+), process result pages as they become available rather than waiting for full completion.

Error handling

Handle 402 (insufficient credits) by notifying your team and falling back to a permissive policy — allow the registration and flag for manual review. Handle 429 (rate limit) with exponential back-off. Never fail a user-facing sign-up flow because of a validation service error; fall back gracefully rather than blocking registration entirely.