VerifyMail API

curl -X POST https://api.verifymailapi.com/v1/check \
  -H "X-API-Key: $VERIFYMAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@mailinator.com"}'

const res = await fetch("https://api.verifymailapi.com/v1/check", {
  method: "POST",
  headers: { "X-API-Key": process.env.VERIFYMAIL_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ email }),
});
const result = await res.json();

switch (result.verdict.recommendation) {
  case "block":
    return reject("This email cannot be used.");
  case "allow_with_flag":
    // Suspicious — route through your verification step.
    user.requires_email_verification = true;
    await sendVerificationEmail(user);
    break;
  case "allow":
    // Clean — proceed normally.
    break;
}

export VERIFYMAIL_KEY="dc_..."

# Preferred:
curl -H "X-API-Key: $VERIFYMAIL_KEY" \
  https://api.verifymailapi.com/v1/check?email=test@example.com

# Also accepted (useful when a client only allows Authorization):
curl -H "Authorization: Bearer $VERIFYMAIL_KEY" \
  https://api.verifymailapi.com/v1/check?email=test@example.com

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 412
X-RateLimit-Reset: 1746920460

if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 1) * 1000;
  await new Promise(r => setTimeout(r, wait));
  return retry(req);
}

POST /v1/check
Idempotency-Key: 2c4f9e1a-7b88-4a3d-9c0f-1e3a5b7c8d9e
X-API-Key: $VERIFYMAIL_KEY
Content-Type: application/json

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

POST https://api.verifymailapi.com/v1/check
X-API-Key: dc_...
X-Risk-Profile: balanced   # optional — strict | balanced | permissive
Content-Type: application/json

{ "email": "user@myagency-solutions.com" }

{
  "meta": {
    "request_id": "req_8d4b3e2f1a6c",
    "email": "user@myagency-solutions.com",
    "domain": "myagency-solutions.com",
    "checked_at": "2026-04-21T10:24:12.391Z",
    "latency_ms": 94,
    "api_version": "2026-04",
    "model_phase": "bootstrap",
    "model_version": "1.0.0",
    "path_taken": "standard",
    "cached": false,
    "cache_age_seconds": null
  },
  "verdict": {
    "recommendation": "block",
    "risk_level": "critical",
    "disposable": false,
    "catch_all": null,
    "catch_all_checked": false,
    "valid_address": true,
    "safe_to_send": false,
    "summary": "Domain registered 4 days ago and matches known disposable infrastructure. Blocked."
  },
  "score": {
    "value": 100,
    "confidence": 0.9,
    "confidence_level": "high",
    "components": {
      "strong_signals": 143,
      "corroborating": 12,
      "trust_adjustments": 0,
      "compounding_bonus": 0,
      "final_clamped": 100
    },
    "thresholds": {
      "block_at": 82,
      "flag_at": 60,
      "your_profile": "balanced"
    },
    "catch_all_detail": null
  },
  "signals": {
    "fired": [
      { "name": "domain_age_under_7_days",            "direction": "risk", "weight": 68 },
      { "name": "mx_known_disposable_infrastructure", "direction": "risk", "weight": 75 },
      { "name": "suspicious_tld",                     "direction": "risk", "weight": 12 }
    ],
    "trust_signals": [],
    "compounding": { "applied": false, "signal_count": 1, "bonus_applied": 0, "explanation": "" }
  }
}

POST /v1/check/domain
X-API-Key: $VERIFYMAIL_KEY
Content-Type: application/json

{"domain": "example.com"}

POST /v1/check/bulk
X-API-Key: $VERIFYMAIL_KEY
Content-Type: application/json

{"emails": ["a@example.com", "b@example.com", "c@example.com"]}

{
  "items": [ /* CheckResponse, CheckResponse, ... */ ],
  "summary": {
    "total": 3,
    "credits_charged": 3,
    "credits_remaining": 8742,
    "elapsed_ms": 327
  }
}

{"index": 4, "result": { /* CheckResponse */ }}
{"index": 0, "result": { /* CheckResponse */ }}
{"index": 1, "result": { /* CheckResponse */ }}
{"index": 2, "result": { /* CheckResponse */ }}
{"index": 3, "result": { /* CheckResponse */ }}
{"event": "summary", "total": 5, "credits_charged": 5, "credits_remaining": 8737, "elapsed_ms": 612}

const res = await fetch(url, { method: "POST", headers, body });
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  const lines = buf.split("\n");
  buf = lines.pop()!;
  for (const line of lines) {
    if (!line) continue;
    const evt = JSON.parse(line);
    if (evt.event === "summary") console.log("done", evt);
    else processRow(evt.index, evt.result);
  }
}

POST /v1/check/async
X-API-Key: $VERIFYMAIL_KEY
Content-Type: application/json

{
  "email": "user@example.com",
  "webhook_url": "https://your-app.example/webhooks/verifymail",
  "webhook_secret": "..."   // optional, any string — used as the HMAC-SHA256 key
}

{
  "request_id": "req_8d4b3e2f1a6c",
  "status": "pending",
  "preliminary": { /* CheckResponse from fast/standard layers */ },
  "webhook_url": "https://your-app.example/webhooks/verifymail",
  "estimated_completion_ms": 6000
}

# List entries
GET    /v1/lists/allow
GET    /v1/lists/block

# Add an entry
POST   /v1/lists/allow   {"domain": "ourcustomerdomain.com"}
POST   /v1/lists/block   {"domain": "abusivedomain.shop"}

# Remove an entry
DELETE /v1/lists/allow/ourcustomerdomain.com

POST /v1/report
X-API-Key: $VERIFYMAIL_KEY
Content-Type: application/json

{
  "domain": "weirddomain.shop",
  "outcome": "confirmed_throwaway",
  "notes": "User signed up, used trial, never paid, never returned."
}

{
  "total_checks": 41203,
  "checks_this_period": 9128,
  "period_start": "2026-05-01T00:00:00+00:00",
  "blocks": 612,
  "allow_with_flag": 240,
  "allows": 8276,
  "avg_latency_ms": 42.1,
  "cache_hit_rate": 0.71,
  "credit_balance_checks": 8742
}

{
  "status": "ok",            // or "degraded"
  "components": {
    "redis": "ok",
    "postgres": "ok",
    "dns": "ok"
  },
  "latency_ms": 18
}

catch_all_detail.detected              =  true
catch_all_detail.probability           =  0.85
catch_all_detail.type                  =  "confirmed"
catch_all_detail.legitimate_use_likely =  false
signals.fired = ["catch_all_new_domain", "mx_known_disposable_infrastructure"]
verdict.recommendation                 =  "block"

catch_all_detail.detected              =  true
catch_all_detail.probability           =  0.85
catch_all_detail.type                  =  "confirmed"
catch_all_detail.legitimate_use_likely =  true
signals.trust_signals = ["catch_all_old_established", "spf_dkim_dmarc_all_present", "domain_age_over_5_years"]
verdict.recommendation                 =  "allow_with_flag"

Content-Type: application/json
User-Agent: VerifyMail-Webhook/1.0
X-VerifyMail-Request-Id: req_abc123
X-VerifyMail-Event: check.completed
X-VerifyMail-Signature: sha256=8c2a5b3e...

import crypto from "node:crypto";

function verify(rawBody: Buffer, signatureHeader: string, secret: string) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  // timingSafeEqual avoids leaking secret length via timing.
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express handler — use express.raw, NOT express.json, so rawBody is preserved.
app.post("/webhooks/verifymail", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-VerifyMail-Signature") ?? "";
  if (!verify(req.body, sig, process.env.VERIFYMAIL_WEBHOOK_SECRET!)) {
    return res.status(401).send("bad signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // event.result is the full CheckResponse.
  await handleCheckCompleted(event);
  res.status(200).end();
});

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# In FastAPI: use Request.body() — JSON parsing happens after verification.
@app.post("/webhooks/verifymail")
async def webhook(request: Request):
    raw = await request.body()
    sig = request.headers.get("X-VerifyMail-Signature", "")
    if not verify(raw, sig, os.environ["VERIFYMAIL_WEBHOOK_SECRET"]):
        raise HTTPException(status_code=401, detail="bad signature")
    event = json.loads(raw)
    await handle_check_completed(event)
    return {"ok": True}

{
  "error": {
    "code": "too_many_requests",
    "http_status": 429,
    "message": "Rate limit exceeded — over 600 req/min on this key. Retry after the window resets.",
    "request_id": "req_8d4b3e2f1a6c",
    "docs_url": "https://verifymailapi.com/docs/rate-limits",
    "limit": 600,
    "reset_at": "2026-05-11T14:30:00Z"
  }
}