Email Verification API: How to Integrate Real-Time Validation

Adding real-time email verification to your application prevents fake signups, reduces bounces, and improves data quality — all before bad addresses enter your database.

This tutorial shows you how to integrate Mailthentic's email verification API into your app, with working code examples in Python and JavaScript.

Getting Started

1. Get your API key

1. Create a free Mailthentic account (100 free credits)
2. Go to Dashboard → API Keys
3. Generate a new API key

2. API endpoint

POST /api/verify/single
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "email": "user@example.com"
}

3. Response format

{
  "job_id": "abc-123-def",
  "status_url": "/api/jobs/abc-123-def/status",
  "results_url": "/api/jobs/abc-123-def/results"
}

Verification is asynchronous — submit the email, then poll the status URL until completion. Single emails typically complete in 1-3 seconds.

Python Integration

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://mailthentic.com/api"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def verify_email(email: str) -> dict:
    """Verify a single email address."""
    # Step 1: Submit verification job
    resp = requests.post(
        f"{BASE_URL}/verify/single",
        json={"email": email},
        headers=HEADERS,
    )
    resp.raise_for_status()
    job = resp.json()

    # Step 2: Poll for results
    for _ in range(30):
        status_resp = requests.get(
            f"{BASE_URL}/jobs/{job['job_id']}/status",
            headers=HEADERS,
        )
        status = status_resp.json()

        if status["status"] == "done":
            results_resp = requests.get(
                f"{BASE_URL}/jobs/{job['job_id']}/results",
                headers=HEADERS,
            )
            return results_resp.json()

        time.sleep(1)

    raise TimeoutError("Verification timed out")

# Usage
result = verify_email("test@example.com")
print(result["results"][0]["status"])  # "deliverable_confirmed", "invalid", etc.

JavaScript Integration

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://mailthentic.com/api';

async function verifyEmail(email) {
  // Step 1: Submit
  const submitResp = await fetch(`${BASE_URL}/verify/single`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email }),
  });
  const job = await submitResp.json();

  // Step 2: Poll
  for (let i = 0; i < 30; i++) {
    await new Promise(r => setTimeout(r, 1000));
    const statusResp = await fetch(
      `${BASE_URL}/jobs/${job.job_id}/status`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    const status = await statusResp.json();

    if (status.status === 'done') {
      const resultsResp = await fetch(
        `${BASE_URL}/jobs/${job.job_id}/results`,
        { headers: { 'Authorization': `Bearer ${API_KEY}` } }
      );
      return await resultsResp.json();
    }
  }
  throw new Error('Verification timed out');
}

// Usage in a signup form
document.getElementById('signup-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const email = document.getElementById('email').value;
  const result = await verifyEmail(email);
  const status = result.results[0].status;

  if (status.startsWith('invalid')) {
    showError('Please enter a valid email address.');
  } else {
    e.target.submit(); // Proceed with signup
  }
});

Signup Form Integration Pattern

The most common use case is verifying emails in real time during user registration:

1. User enters email on your signup form
2. On form submit (or on blur), call the verification API
3. If invalid or disposable → show error, prevent submission
4. If valid → proceed with registration
5. If risky (catch-all) → allow but flag for monitoring
6. If unknown (timeout) → allow and verify later asynchronously

Handling Verification Statuses

Best Practices

• Verify on blur, not on submit. Start verification when the user leaves the email field — by the time they finish the form, results are ready.
• Cache results. Don't re-verify the same email within 24 hours.
• Handle timeouts gracefully. If verification takes too long, let the user proceed and verify asynchronously.
• Don't block on risky. Catch-all or ambiguous results should be allowed with a flag, not rejected.
• Rate limit your calls. Batch signups or implement a queue for high-traffic forms.

For full API documentation including bulk verification, webhooks, and all response fields, see our API documentation page.