Email Verification API: Complete Integration Guide

Adding email verification to your application is one of the highest-ROI engineering decisions you can make. It prevents fake sign-ups, reduces bounce rates, and protects your sender reputation from day one. This guide walks you through a complete integration — from authentication to production deployment.

Why Verify at the API Level?

Client-side regex checks catch obvious typos, but they can't tell you whether an address actually exists, whether the domain has valid MX records, or whether the mailbox is a disposable throwaway. An API-level verification service performs dozens of checks in real time, giving you a definitive answer before the address ever enters your database.

Authentication

Most email verification APIs use API key authentication via a header. Here's a typical setup:

// Set your API key in environment variables
const API_KEY = process.env.VERIFOX_API_KEY;

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

Security best practice: Never expose your API key in client-side code. All verification requests should go through your backend server or a serverless function.

Single Email Verification

The most common use case is verifying a single email in real time — typically when a user fills out a sign-up form or contact form. The request is simple:

const response = await fetch("https://api.verifox.ai/v1/verify", {
  method: "POST",
  headers,
  body: JSON.stringify({ email: "user@example.com" })
});

const result = await response.json();
// result.status: "valid" | "invalid" | "risky" | "unknown"
// result.checks: { mx: true, smtp: true, disposable: false, ... }

The response typically includes a top-level status and a breakdown of individual checks:

• MX record check — Does the domain have mail servers configured?
• SMTP verification — Does the mailbox actually exist on that server?
• Disposable detection — Is this a temporary/throwaway address?
• Role account detection — Is this a generic address like info@ or admin@?
• Free provider detection — Is this Gmail, Yahoo, Outlook, etc.?
• Catch-all detection — Does the domain accept mail for any address?

Bulk Email Verification

When you need to clean an existing list, the bulk endpoint lets you submit thousands of emails in a single request. Since bulk verification is asynchronous, the flow is different:

// Step 1: Submit the batch
const submitResponse = await fetch("https://api.verifox.ai/v1/verify/bulk", {
  method: "POST",
  headers,
  body: JSON.stringify({
    emails: ["user1@example.com", "user2@example.com", /* ... */]
  })
});

const { batchId } = await submitResponse.json();

// Step 2: Poll for results (or use webhooks)
const statusResponse = await fetch(
  `https://api.verifox.ai/v1/verify/bulk/${batchId}`,
  { headers }
);

const batch = await statusResponse.json();
// batch.status: "processing" | "completed"
// batch.progress: 0.75  (75% done)
// batch.results: [...] (when completed)

Using Webhooks Instead of Polling

For a cleaner integration, configure a webhook URL so you get notified automatically when a bulk job finishes. This eliminates the need for polling loops and reduces unnecessary API calls.

// When submitting, include a webhook URL
const submitResponse = await fetch("https://api.verifox.ai/v1/verify/bulk", {
  method: "POST",
  headers,
  body: JSON.stringify({
    emails: [...],
    webhookUrl: "https://yourapp.com/api/webhooks/verifox"
  })
});

Your webhook endpoint will receive a POST request with the complete results once processing is finished. Make sure to verify the webhook signature to ensure the request is authentic.

Handling Responses in Your Application

How you handle each status depends on your use case. Here's a sensible default strategy:

function handleVerificationResult(result) {
  switch (result.status) {
    case "valid":
      // Accept the email — it's safe to send to
      return { accept: true };

    case "invalid":
      // Reject — this address will hard bounce
      return { accept: false, reason: "This email address doesn't exist." };

    case "risky":
      // Accept with caution — flag for review
      // Risky includes catch-all domains and role accounts
      return { accept: true, flagged: true };

    case "unknown":
      // The server didn't respond — accept but monitor
      return { accept: true, flagged: true };
  }
}

Rate Limits and Error Handling

Production integrations need to handle rate limits gracefully. Look for the 429 Too Many Requests status code and implement exponential backoff:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch("https://api.verifox.ai/v1/verify", {
      method: "POST",
      headers,
      body: JSON.stringify({ email })
    });

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 1;
      await new Promise(r => setTimeout(r, retryAfter * 1000 * (attempt + 1)));
      continue;
    }

    return await response.json();
  }
  throw new Error("Max retries exceeded");
}

Production Checklist

Before going live, make sure you've covered these essentials:

1. API key is stored securely — Use environment variables, never hard-code
2. Verification happens server-side — Never call the API from the browser
3. Error handling is robust — Gracefully handle timeouts, rate limits, and network errors
4. Results are cached — Don't re-verify the same address on every form submission; cache results for 24-48 hours
5. User experience is smooth — Show a loading state during verification and provide clear error messages
6. Monitoring is in place — Track API response times, error rates, and credit usage

With a solid integration in place, you'll catch bad addresses before they enter your funnel, keeping your lists clean and your deliverability strong from the start.