Response Schema

Every validation request returns a consistent JSON structure with the email, validity status, score, individual check results, and recommendations.

Response Structure

{
  "email": "user@example.com",
  "severity": "valid",
  "isValid": true,
  "score": 95,
  "deliverabilityScore": 92,
  "checks": {
    "syntax": { ... },
    "domain": { ... },
    "mxRecords": { ... },
    "disposable": { ... },
    "roleBased": { ... },
    "catchAll": { ... }
  },
  "recommendations": ["Email passed all validation checks"],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processingTime": 94
}

Top-Level Fields

Field	Type	Description
`email`	string	The validated email address
`severity`	string	`valid`, `warning`, or `invalid`
`isValid`	boolean	Quick validity check (score >= 70)
`score`	number	Confidence score (0-100)
`deliverabilityScore`	number	Predicted deliverability (Pro+ tiers)
`checks`	object	Individual validation check results
`recommendations`	string[]	Actionable suggestions
`timestamp`	string	ISO 8601 validation timestamp
`processingTime`	number	Processing time in milliseconds

Severity Levels

Severity	Score Range	Meaning
`valid`	70-100	Email is safe to use
`warning`	40-69	Email has concerns, use caution
`invalid`	0-39	Email should not be used

Score Interpretation

The score combines results from all validation checks:

Score	Quality	Use Case
90-100	Excellent	Safe for all purposes
70-89	Good	Safe for transactional email
50-69	Fair	Consider for marketing with caution
30-49	Poor	High risk, manual review recommended
0-29	Invalid	Do not send email

Check Result Structure

Each check in the checks object follows this structure:

{
  "check": "syntax",
  "passed": true,
  "status": "pass",
  "category": "syntax",
  "reason": "Email syntax is valid (RFC 5322 compliant)",
  "action": "allow",
  "confidence": 100,
  "metadata": {}
}

Field	Type	Description
`check`	string	Check identifier
`passed`	boolean	Whether this check passed
`status`	string	`pass`, `fail`, `warn`, `skip`, `error`
`category`	string	Check category
`reason`	string	Human-readable explanation
`action`	string	Recommended action
`confidence`	number	Certainty level (0-100)
`metadata`	object	Additional check-specific data

Status Values

Status	Meaning
`pass`	No issues found
`fail`	Blocking issue detected
`warn`	Concern found, not blocking
`skip`	Check was skipped (not available on tier)
`error`	Check failed to execute

Action Values

Action	Meaning
`allow`	Safe to proceed
`block`	Should reject
`flag`	Mark for monitoring
`review`	Requires manual review

Category	Description
`syntax`	Email format validation
`domain`	Domain and DNS checks
`mailbox`	Mailbox existence verification
`reputation`	Reputation and blacklist checks
`quality`	Email quality indicators
`security`	Security and fraud detection

Available Checks

The checks object contains results for each validation performed:

Core Checks (All Tiers)

Check	Category	Description
`syntax`	syntax	RFC 5322 format validation
`domain`	domain	Domain DNS resolution
`mxRecords`	domain	Mail server configuration
`disposable`	reputation	Temporary email detection
`roleBased`	quality	Generic address detection

Hobby+ Checks

Check	Category	Description
`catchAll`	quality	Catch-all domain detection
`typoSuggestion`	quality	Common typo correction
`freeEmail`	quality	Free provider detection

Pro+ Checks

Check	Category	Description
`spamTrap`	reputation	Spam trap detection
`emailAuthentication`	security	SPF/DKIM/DMARC analysis
`blacklist`	reputation	Blacklist status
`domainTrust`	security	Domain trust score
`fraudDetection`	security	AI fraud analysis

Business+ Checks

Check	Category	Description
`smtpVerification`	mailbox	Direct SMTP verification
`corporateEmail`	quality	Business email detection
`mailboxProvider`	quality	Infrastructure identification

Example Responses

Valid Email

{
  "email": "john.doe@company.com",
  "severity": "valid",
  "isValid": true,
  "score": 95,
  "checks": {
    "syntax": {
      "check": "syntax",
      "passed": true,
      "status": "pass",
      "category": "syntax",
      "reason": "Email syntax is valid (RFC 5322 compliant)",
      "action": "allow",
      "confidence": 100
    },
    "domain": {
      "check": "domain",
      "passed": true,
      "status": "pass",
      "category": "domain",
      "reason": "Domain exists and resolves",
      "confidence": 100,
      "metadata": {
        "hasA": true,
        "hasAAAA": true
      }
    },
    "mxRecords": {
      "check": "mxRecords",
      "passed": true,
      "status": "pass",
      "category": "domain",
      "reason": "Found 2 MX records",
      "confidence": 100,
      "metadata": {
        "mxRecords": ["mx1.company.com", "mx2.company.com"],
        "primaryMx": "mx1.company.com",
        "mxCount": 2
      }
    },
    "disposable": {
      "check": "disposable",
      "passed": true,
      "status": "pass",
      "category": "reputation",
      "reason": "Not a disposable email provider",
      "action": "allow",
      "confidence": 100,
      "metadata": {
        "isDisposable": false
      }
    },
    "roleBased": {
      "check": "roleBased",
      "passed": true,
      "status": "pass",
      "category": "quality",
      "reason": "Personal email address",
      "action": "allow",
      "confidence": 95,
      "metadata": {
        "isRoleBased": false
      }
    }
  },
  "recommendations": ["Email passed all validation checks"],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processingTime": 94
}

Invalid Email (Disposable)

{
  "email": "test@mailinator.com",
  "severity": "invalid",
  "isValid": false,
  "score": 25,
  "checks": {
    "syntax": {
      "check": "syntax",
      "passed": true,
      "status": "pass",
      "category": "syntax",
      "reason": "Email syntax is valid",
      "confidence": 100
    },
    "disposable": {
      "check": "disposable",
      "passed": false,
      "status": "fail",
      "category": "reputation",
      "reason": "Disposable email provider detected (mailinator.com)",
      "action": "block",
      "confidence": 99,
      "metadata": {
        "isDisposable": true,
        "provider": "mailinator.com"
      }
    }
  },
  "recommendations": [
    "Disposable email detected - consider blocking",
    "Request a permanent email address"
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processingTime": 45
}

Warning Email (Role-Based)

{
  "email": "info@company.com",
  "severity": "warning",
  "isValid": true,
  "score": 65,
  "checks": {
    "syntax": {
      "check": "syntax",
      "passed": true,
      "status": "pass",
      "category": "syntax",
      "reason": "Email syntax is valid",
      "confidence": 100
    },
    "roleBased": {
      "check": "roleBased",
      "passed": false,
      "status": "warn",
      "category": "quality",
      "reason": "Role-based email address (info@)",
      "action": "flag",
      "confidence": 95,
      "metadata": {
        "isRoleBased": true,
        "roleType": "info",
        "riskLevel": "medium"
      }
    }
  },
  "recommendations": [
    "Role-based email detected - may have multiple recipients",
    "Consider requesting a personal email for marketing"
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processingTime": 67
}

Email with Typo

{
  "email": "user@gmial.com",
  "severity": "warning",
  "isValid": true,
  "score": 55,
  "checks": {
    "typoSuggestion": {
      "check": "typoSuggestion",
      "passed": false,
      "status": "warn",
      "category": "quality",
      "reason": "Possible typo detected: gmial.com → gmail.com",
      "action": "review",
      "confidence": 95,
      "metadata": {
        "hasTypo": true,
        "originalDomain": "gmial.com",
        "suggestion": "gmail.com"
      }
    }
  },
  "recommendations": [
    "Did you mean user@gmail.com?",
    "Common typo detected in domain"
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "processingTime": 52
}

Metadata Reference

Domain Check Metadata

{
  "hasA": true,
  "hasAAAA": true
}

MX Records Metadata

{
  "mxRecords": ["mx1.example.com", "mx2.example.com"],
  "primaryMx": "mx1.example.com",
  "mxCount": 2
}

Disposable Metadata

{
  "isDisposable": true,
  "provider": "mailinator.com"
}

Role-Based Metadata

{
  "isRoleBased": true,
  "roleType": "support",
  "riskLevel": "medium"
}

Catch-All Metadata

{
  "isCatchAll": true
}

Typo Suggestion Metadata

{
  "hasTypo": true,
  "originalDomain": "gmial.com",
  "suggestion": "gmail.com"
}

Free Email Metadata

{
  "isFreeEmail": true,
  "provider": "Google",
  "providerName": "Gmail"
}

Email Authentication Metadata

{
  "spf": { "exists": true, "policy": "-all" },
  "dkim": { "exists": true },
  "dmarc": { "exists": true, "policy": "reject" }
}

SMTP Verification Metadata

{
  "mailboxExists": true,
  "isGreylisted": false
}

Corporate Email Metadata

{
  "isCorporate": true,
  "provider": "microsoft365",
  "companyDomain": "acme.com"
}

Mailbox Provider Metadata

{
  "provider": "Google Workspace",
  "infrastructure": "google_workspace"
}

SDK Type Definitions

interface EmailValidationResult {
  email: string;
  severity: 'valid' | 'warning' | 'invalid';
  isValid: boolean;
  score: number;
  deliverabilityScore?: number;
  checks: ValidationChecks;
  recommendations: string[];
  timestamp: string;
  processingTime: number;
}

interface ValidationCheck {
  check: string;
  passed: boolean;
  status: 'pass' | 'fail' | 'warn' | 'skip' | 'error';
  category: 'syntax' | 'domain' | 'mailbox' | 'reputation' | 'quality' | 'security';
  reason: string;
  action: 'allow' | 'block' | 'flag' | 'review';
  confidence: number;
  metadata?: Record<string, unknown>;
}