Email Verification API Documentation: A Developer's Integration Guide

If you are a developer integrating email verification into your application, this guide covers the technical details you need: API structure, request and response formats, error handling, rate limiting, and implementation patterns.

API Overview

CatchallVerifier provides a RESTful API for email verification. The API supports both single-email verification (real-time checks) and bulk verification (batch processing). Full documentation is available through readme.io, linked from the CatchallVerifier dashboard.

Authentication uses an API key passed as a header or query parameter. You get your API key from the CatchallVerifier dashboard after signup. The free trial includes 100 verification credits to test the integration before committing to a paid plan.

Single Email Verification

For real-time verification (form validation, CRM integration), use the single-email endpoint. Send a GET or POST request with the email address as a parameter. The API returns a JSON response with the verification result.

The response includes: status (the primary verification result: valid, invalid, catch_all, risky, unknown, disposable), sub_status (additional context about the result), confidence_score (numerical confidence in the result), domain_info (details about the email domain including catch-all status), and processing_time (how long the verification took).

Typical response times are under 1 second for standard domains and 1-3 seconds for catch-all domains that require deeper analysis. Design your integration to handle these response times asynchronously to avoid blocking user interfaces.

Bulk Verification

For batch processing, use the bulk verification endpoint. Upload a list of email addresses (CSV format) and receive a job ID. Poll the status endpoint with the job ID to check progress. When processing is complete, download the results as a CSV with verification statuses appended.

Bulk verification is asynchronous by design. Processing time depends on list size and the proportion of catch-all domains. A list of 10,000 addresses typically processes in 15-60 minutes. Plan your workflow accordingly.

Error Handling

The API uses standard HTTP status codes: 200 for successful verification, 400 for invalid request parameters (bad email format, missing fields), 401 for authentication failure (invalid or missing API key), 429 for rate limit exceeded, and 500 for server-side errors.

For 429 (rate limited) responses, implement exponential backoff. Wait 1 second, then 2, then 4, up to a maximum of 30 seconds between retries. The rate limit resets on a sliding window, so backing off will resolve the issue without intervention.

For 500 errors, retry up to 3 times with backoff. If the error persists, log it and fall back to a default behavior (accept the email with a "pending verification" status, or queue it for later verification).

Rate Limiting

The API enforces rate limits to ensure consistent performance across all users. Current limits are documented in the API reference. For most plans, the limits are generous enough for real-time form validation. If you need higher throughput, contact support for custom rate limit arrangements.

Implement rate limiting on your side as well. If you are verifying emails in a loop (processing a database, for example), add delays between requests to stay within limits. A simple approach: verify one email per second for real-time use, or batch into bulk verification for large volumes.

Implementation Patterns

Form validation pattern: When a user submits a form, call the API before saving the record. Show the verification result inline. For valid addresses, proceed normally. For invalid, show an error. For catch-all, accept but flag for follow-up verification. Handle API timeouts by accepting the submission and queueing background verification.

CRM integration pattern: Use webhooks or event triggers from your CRM to call the API when new contacts are created. Write results back to custom fields. Implement a queue to handle bursts of new contacts without exceeding rate limits.

Batch processing pattern: Export contacts periodically, submit to bulk API, poll for results, import verification status back to your system. Schedule this to run nightly or weekly depending on your data volume.

Waterfall enrichment pattern: After finding an email through enrichment, verify it immediately. If the result is catch-all, run the specialized catch-all verification. Only pass confirmed deliverable addresses downstream to your outreach tools.

Code Examples

The API documentation at readme.io includes code examples in Python, JavaScript/Node.js, cURL, Ruby, and PHP. These cover the most common integration scenarios and can be adapted to your specific stack.

For Python: the requests library handles API calls cleanly. For JavaScript/Node.js: axios or the built-in fetch API work well. For server-side integrations: use your framework's HTTP client library and handle responses asynchronously.

Webhook Callbacks

For bulk verification, the API supports webhook callbacks. Instead of polling for results, provide a callback URL when submitting a bulk job. The API will POST the results to your URL when processing is complete. This is the preferred approach for production integrations because it eliminates polling overhead.

Ensure your webhook endpoint is idempotent (handles duplicate callbacks gracefully) and responds with a 200 status code promptly. If the callback fails, the API retries up to 3 times with exponential backoff.

Security Considerations

Never expose your API key in client-side code (JavaScript running in the browser). All API calls should go through your backend server. Use environment variables to store the API key, not hardcoded values. Rotate your API key periodically, especially if you suspect it has been compromised.

For form validation, create a server-side endpoint that your form calls. The endpoint calls the CatchallVerifier API with the API key stored securely on the server, then returns just the verification result to the client. This keeps your API key hidden while providing real-time verification feedback to users.