Getting Started

The Email Risk Radar is a single JSON-over-HTTPS API. There's no SDK required — every endpoint is a plain REST call, authenticated with a bearer API key, returning a consistent response shape you can parse the same way in any language.

Base URL

base-url

https://api.emailriskradar.com

Every endpoint in this documentation is relative to that base URL and versioned under /v1 (e.g. /v1/email/check).

Your first request

Create an API key from the dashboard first (see Authentication), then check an address:

curl https://api.emailriskradar.com/v1/email/check \
  -H "Authorization: Bearer $EMAIL_RISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

response.json

{
  "email": "user@example.com",
  "decision": "allow",
  "risk": { "score": 5, "level": "low", "confidence": 0.8, "breakdown": { "email_quality": 0, "domain": 0, "disposable": 0, "provider": 0, "deliverability": 0, "reputation": 0 } },
  "verification": { "status": "likely_valid", "domain": "verified", "mailbox": "unconfirmed", "confidence": 0.75 },
  "deliverability": { "status": "likely_deliverable", "confidence": 0.75 },
  "email_quality": { "score": 95, "classification": "normal" },
  "local_part_analysis": { "length": 4, "contains_numbers": false, "number_ratio": 0, "entropy": 1.5, "repeated_character_ratio": 0, "keyboard_pattern": false, "name_like": true, "randomness": "low", "classification": "normal" },
  "signals": [],
  "email_details": { "normalized": "user@example.com", "local_part": "user", "domain": "example.com" },
  "checks": { "syntax_valid": true, "domain_exists": true, "mx_found": true, "smtp_check": "unknown", "disposable": false, "free_provider": false, "role_based": false, "catch_all": false, "typo_detected": false },
  "domain": { "domain": "example.com", "provider": null, "type": "business", "free_provider": false, "disposable": false, "has_mx": true, "spf": true, "dmarc": false, "reputation": { "score": 78, "classification": "neutral", "confidence": 0.75 }, "infrastructure": { "mail_provider": null, "classification": "self_hosted_or_unknown", "provider_type": null }, "domain_age": { "days": 4210, "classification": "established" } },
  "suggestion": null,
  "meta": { "processing_ms": 84, "cached": false, "mode": "standard", "context": "generic", "request_id": "req_..." }
}

The response shape, at a glance

Field	What it tells you
decision	The routing decision: allow, review, or block
risk	0–100 score, level, confidence, and a per-category breakdown
verification / deliverability	Separate assessments of address validity vs. mailbox reachability
signals	Every specific fact that contributed to the score, with severity and point impact
checks	The raw pass/fail results each signal is derived from
domain	Domain-level intelligence: reputation, infrastructure, age, SPF/DMARC
meta	Request metadata: processing time, cache status, mode, and context used

See the Endpoints Reference for the full field-by-field breakdown, and Best Practices for how to choose a mode and structure the request around your actual flow (blocking vs. background).

Where to go next

Authentication — how API keys work, live vs. test environments
Endpoints Reference — every endpoint, parameter, and error code
Best Practices — checking at signup without blocking the flow, mode selection, error handling
Code Examples — a minimal client, bulk polling, and framework integration in cURL, JavaScript/Node.js, Python, PHP, and Go
Use Cases — signup screening, lead scoring, checkout fraud prevention, bulk list cleanup