Email verification API: how to integrate one in your app (with code)

An email verification API is a REST endpoint that takes an email address and returns a verdict — valid, invalid, risky, disposable, catch-all, role-based or spam trap — in under two seconds. This guide walks through integrating one in your app, with copy-paste code in cURL, JavaScript, PHP and Python, plus the right patterns for signup forms, CRMs and queues.

What is an email verification API?

It's a real-time HTTP API. You send a single address, the service runs DNS, MX, SMTP and reputation checks in parallel, and returns structured JSON. The best APIs respond in 1–2 seconds, support bearer-token authentication, and never log or sell your data.

When should you use the API (vs. bulk upload)?

• Signup forms: verify before account creation. Reject typos, disposable domains and obvious invalids at the door.
• CRM enrichment: verify leads as they enter your CRM. Tag invalid contacts for cleanup, tag risky ones for nurturing.
• Lead-gen forms: protect against form spam and skewed analytics.
• Webhook pipelines: verify each new contact in your Zapier / n8n / Make workflow before pushing to downstream tools.

Use bulk upload for cleaning an existing list of more than ~5,000 addresses. Anything smaller is fine to run through the API.

Step 1: Generate an API key

In your MailoClean dashboard, go to API Keys → Generate. Keep the key in a secret manager — never commit it to git. Each key has its own rate limit (60 requests/minute by default).

Step 2: Make your first request

cURL

curl -X POST "https://mailoclean.com/api/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"hello@company.com"}'

JavaScript (fetch)

const res = await fetch("https://mailoclean.com/api/v1/verify", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.MAILOCLEAN_KEY}`,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({ email: "hello@company.com" })
});
const data = await res.json();
if (data.status !== "valid") {
  throw new Error(`Email rejected: ${data.status}`);
}

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.mailoclean.key'))
    ->acceptJson()
    ->post('https://mailoclean.com/api/v1/verify', [
        'email' => $request->input('email'),
    ]);

$result = $response->json();
abort_if($result['status'] !== 'valid', 422, 'Please use a valid email.');

Python (requests)

import os, requests

res = requests.post(
    "https://mailoclean.com/api/v1/verify",
    headers={"Authorization": f"Bearer {os.environ['MAILOCLEAN_KEY']}"},
    json={"email": "hello@company.com"},
    timeout=10,
)
result = res.json()
if result["status"] != "valid":
    raise ValueError(f"Bad email: {result['status']}")

Step 3: Handle the response

The response always returns a top-level status, a score (0–100), and a checks object. Example for a deliverable Gmail address:

{
  "email": "hello@company.com",
  "status": "valid",
  "score": 95,
  "checks": {
    "syntax": true,
    "domain": true,
    "mx": true,
    "smtp": true,
    "mailbox_exists": true,
    "disposable": true,
    "catch_all": true,
    "role_based": true
  }
}

Map each status to your business logic:

• valid → accept
• invalid, disposable, spamtrap → reject
• catch_all, role_based → accept but tag as risky for segmentation
• risky, unknown → up to you; many teams accept with a warning

Step 4: Wire it into your signup form

The most common pattern: front-end submits to your server, your server hits MailoClean, and your server decides whether to create the account.

// pseudo-code for any framework
app.post('/signup', async (req, res) => {
  const verify = await mailoclean.verify(req.body.email);

  if (verify.status === 'invalid' || verify.status === 'disposable') {
    return res.status(422).json({ error: 'Please use a permanent email address.' });
  }

  const user = await createUser({ ...req.body });
  return res.json({ user });
});

Best practices

• Cache results for 24h. An address verified an hour ago doesn't need to be reverified. MailoClean does this for you on the server, so repeated checks within 24h are free.
• Retry on 429 with exponential backoff. The default rate limit is 60 requests/minute. Use a short queue or backoff (1s, 2s, 4s, 8s) instead of failing hard.
• Never block UI on verification. Verify on submit, not on every keystroke. Show a small spinner; the call should complete in under 2 seconds.
• Fail open on network errors. If the verification call times out, accept the signup with a "to verify" flag and reverify in a background job. Better than locking real users out during a network blip.
• Keep your API key server-side. Never expose it in client-side JavaScript or a mobile app binary.

Common error codes

Frequently asked questions

How fast is the email verification API?

MailoClean averages 1.4s p50 and 2.1s p95 end-to-end, including SMTP handshake. For signup forms that means an imperceptible delay between submit and account creation.

Does it work with Salesforce, HubSpot or Pipedrive?

Yes — any tool that supports outbound webhooks or workflow HTTP calls can hit the verification API. Native integrations are on the roadmap; for now the REST endpoint covers all use cases.

How much does the API cost?

Pay-as-you-go from $0.004 per credit, or $0.0008 at bundle volumes. Credits never expire and are shared with bulk and single verification. See pricing.

Is there a free tier?

New accounts get free starter credits, plus 5 free homepage verifications per day per IP. Sign up to get keys.

Ready to integrate?

Read the full API documentation, copy a snippet, and ship in 10 minutes. Questions? Email support@mailoclean.com.