Email verification in five minutes.

Authentication

All requests require a Bearer token in the Authorization header. Get your key from API & Usage inside the app.

Authorization: Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://app.emailzeno.com/api

Verify a single email

Synchronously probe one address. Returns full probe result + quality score. Costs 1 credit — deducted before probing, refunded automatically if the engine is unavailable.

• curl
• JavaScript
• PHP
• Python

curl -X POST https://app.emailzeno.com/api/v1/verify \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

const res = await fetch('https://app.emailzeno.com/api/v1/verify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: '[email protected]' }),
});
const data = await res.json();
console.log(data.status); // "valid"

$ch = curl_init('https://app.emailzeno.com/api/v1/verify');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['email' => '[email protected]']),
]);
$data = json_decode(curl_exec($ch), true);
echo $data['status']; // valid

import requests

response = requests.post(
    'https://app.emailzeno.com/api/v1/verify',
    headers={
        'Authorization': 'Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={'email': '[email protected]'},
)
data = response.json()
print(data['status'])  # valid

Response 200 OK

{
  "email": "[email protected]",
  "status": "valid",
  "flags": [],
  "smtp_code": 250,
  "smtp_message": "2.1.5 OK",
  "mx_host": "aspmx.l.google.com",
  "duration_ms": 312.45,
  "quality_score": 92,
  "quality_band": "excellent",
  "mx_provider": "Google Workspace",
  "is_free_mailbox": false,
  "signals": [
    { "key": "syntax",     "label": "Syntax check",      "kind": "ok" },
    { "key": "disposable", "label": "Disposable domain", "kind": "ok" },
    { "key": "mx",         "label": "MX records",        "kind": "ok" },
    { "key": "mailbox",    "label": "Mailbox probe",     "kind": "ok" }
  ],
  "credit_charged": true,
  "credit_skip_reason": null,
  "state": "deliverable",
  "reason": "accepted_email",
  "score": 92,
  "free": false,
  "role": false,
  "disposable": false,
  "accept_all": false,
  "mailbox_full": false,
  "smtp_provider": "Google Workspace",
  "did_you_mean": null,
  "domain": "example.com",
  "user": "test",
  "mx_record": "aspmx.l.google.com",
  "duration": 0.3125
}

Response fields

Verify a batch (up to 1,000)

Enqueue an async job. Returns HTTP 202 immediately with a job_id. Poll GET /api/jobs/{job_id} for progress and results. Costs 1 credit per email, all deducted upfront — no partial runs on low balance.

• curl
• JavaScript
• PHP
• Python

curl -X POST https://app.emailzeno.com/api/v1/verify/bulk \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]"]}'

const res = await fetch('https://app.emailzeno.com/api/v1/verify/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ emails: ['[email protected]', '[email protected]'] }),
});
const { job_id } = await res.json(); // 202 Accepted
// Poll: GET /api/jobs/${job_id}

$ch = curl_init('https://app.emailzeno.com/api/v1/verify/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'emails' => ['[email protected]', '[email protected]'],
    ]),
]);
$data  = json_decode(curl_exec($ch), true);
$jobId = $data['job_id']; // poll GET /api/jobs/{$jobId}

import requests

response = requests.post(
    'https://app.emailzeno.com/api/v1/verify/bulk',
    headers={
        'Authorization': 'Bearer ec_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={'emails': ['[email protected]', '[email protected]']},
)
job_id = response.json()['job_id']  # poll GET /api/jobs/{job_id}

Response 202 Accepted

{
  "job_id": 42,
  "email_count": 2,
  "status": "queued",
  "message": "Job queued. Poll /api/jobs/{job_id} for status.",
  "credits_used": 2
}

Credit billing & refund taxonomy

Credits are deducted before each verification. Certain statuses trigger automatic refunds. The response always includes credit_charged and credit_skip_reason.

deep_probe request param

Paid-tier only. When deep_probe: true, disposable and role-based addresses receive a full mailbox probe instead of early-exit. Credits are always charged. Free-tier ignores the flag silently.

Error codes

402 example (bulk)

{
  "error": "Insufficient credits. Need 50, balance is 10.",
  "code": "insufficient_credits",
  "required": 50,
  "balance": 10
}

Rate limits

Exceeded requests receive HTTP 429 with a Retry-After header indicating how many seconds to wait.

Notifications

Subscribe to delivery events via webhook, Telegram, or Pushbullet. Configure channels at Settings → Notifications. Every enabled channel fires for each event you opt in to — no polling required.

Events

Webhook delivery

emailzeno signs every outbound webhook with HMAC-SHA256 over the raw request body using your personal secret. Three headers are included on every delivery:

Payload example — job.completed

{
  "event": "job.completed",
  "occurred_at": "2026-05-13T07:10:00Z",
  "user_id": 42,
  "data": {
    "job_id": 1234,
    "status": "done",
    "summary": { "total": 5000, "valid": 4200, "invalid": 800 },
    "job_url": "https://app.emailzeno.com/jobs/1234"
  }
}

Verifying the signature

Compare the computed HMAC against the value in X-EC-Notification-Signature using a constant-time comparison. Use the raw request body — before any JSON parsing.

• PHP
• Node.js

<?php
$secret    = getenv('EC_WEBHOOK_SECRET'); // your per-account secret
$rawBody   = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_X_EC_NOTIFICATION_SIGNATURE'] ?? '';

// Header format: "sha256={hex}"
[, $receivedHex] = explode('=', $sigHeader, 2);

$expected = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $receivedHex)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
// process $payload['event'] ...

import crypto from 'crypto';

// Express example — use express.raw() so body is a Buffer
app.post('/webhooks/ec', express.raw({ type: 'application/json' }), (req, res) => {
  const secret      = process.env.EC_WEBHOOK_SECRET;
  const sigHeader   = req.headers['x-ec-notification-signature'] ?? '';
  const receivedHex = sigHeader.replace('sha256=', '');

  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body) // raw Buffer, not parsed JSON
    .digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedHex),
  );
  if (!valid) return res.status(401).send('Invalid signature');

  const payload = JSON.parse(req.body.toString());
  // process payload.event ...
  res.sendStatus(200);
});

Form Validation Widget

Add real-time email validation to any web form with a single line of code. The widget automatically validates email addresses as your visitors type, blocking invalid emails before they enter your system.

Method 1 (recommended): Widget Generator

Visit app.emailzeno.com/widget-builder to create a widget configuration, then copy the generated data-config-id snippet:

<script src="https://app.emailzeno.com/widget.js"
  data-config-id="your-uuid-here"></script>

Method 2 (manual): data-key attribute

Generate a form API key from Settings → API Keys, then paste this script tag before </body>:

<script src="https://emailzeno.com/assets/js/form-validation-widget.js"
  data-key="YOUR_PUBLIC_API_KEY"></script>

Embed format

Configure the widget via data-key for your API key and optional data-config for behaviour overrides:

<script src="https://emailzeno.com/assets/js/form-validation-widget.js"
  data-key="YOUR_PUBLIC_API_KEY"
  data-config='{"mode":"block","risky":"allow"}'></script>

Configuration options

Platform guides

The widget works with any website or form builder:

• Plain HTML: Add the script tag before </body> on any page with a form.
• WordPress: Paste in Appearance → Theme File Editor (footer.php) or use a header/footer plugin.
• Webflow: Go to Project Settings → Custom Code and paste in Footer Code section.
• Shopify: Open theme.liquid and paste before the closing </body> tag.
• React / Next.js: Use useEffect to create the script element dynamically. The widget includes a MutationObserver that handles dynamic forms and SPAs automatically.

Fail-open behaviour

The widget never blocks legitimate users due to infrastructure issues:

• If the API is unreachable, the form submits normally
• Block mode only prevents submission when the API explicitly returns invalid

Security

Form API keys are designed for public embedding and are protected by domain restrictions, per-IP rate limiting, and prefix-based scoping (test_ for dev, live_ for production).

Credit usage

Form validations use the same credit system. Credits are consumed for definitive results (valid / invalid) but not for uncertain results (unknown). All form validation keys share the same credit pool as your API keys.

Interactive API explorer

Full OpenAPI spec rendered below. Paste your API key to try requests live.