Email Verification API

Overview

The Email Verification API validates email addresses and provides comprehensive risk analysis including:

Format validation and syntax checking
Domain and MX record verification
Disposable email detection
Spam trap and honeypot identification
Fraud risk scoring
Data breach detection
Associated accounts information

This endpoint requires an IPQualityScore API key. Set IPQUALITYSCORE_API_KEY in your environment variables.

Endpoint

POST /api/email/verify

Request

Headers

Content-Type: application/json

Body Parameters

string

required

Email address to verify. Must be a valid email format.Will be automatically trimmed and converted to lowercase.Example: "[email protected]"

Request Example

curl -X POST http://localhost:3000/api/email/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Response

success

boolean

Always true for successful verification requests

result

EmailVerificationResult

Comprehensive email verification data

Show EmailVerificationResult properties

Core Validation

valid

boolean

Overall email validity (true if email exists and is deliverable)

disposable

boolean

Whether the email is from a disposable/temporary email provider

catchAll

boolean

Whether the domain accepts all emails (catch-all configuration)

Risk Scoring

fraudScore

number

Overall fraud risk score (0-100, higher = more risky)

spamTrapScore

string

Likelihood of being a spam trap (“none”, “low”, “medium”, “high”)

recentAbuse

boolean

Email has been recently associated with abusive behavior

leaked

boolean

Email appears in known data breaches

frequentComplainer

boolean

User frequently marks emails as spam

Deliverability

deliverability

string

Email deliverability status (“high”, “medium”, “low”, “undeliverable”)

dnsValid

boolean

Domain has valid DNS records

mxRecords

boolean

Domain has valid MX (mail exchange) records

smtpScore

number

SMTP validation score (0-4, higher = more validated)

Email Details

sanitizedEmail

string

Cleaned and standardized email address

suggestedDomain

string

Suggested domain if typo detected (e.g., “gmail.com” for “gmai.com”)

honeypot

boolean

Email is a honeypot trap

generic

boolean

Email uses a generic/role-based address (info@, admin@, support@)

common

boolean

Email is from a common free email provider

Domain Information

domainAge

object

Domain registration age

Show domainAge properties

human

string

Human-readable age (e.g., “5 years”)

timestamp

number

Unix timestamp of domain registration

iso

string

ISO 8601 formatted date

Account Information

firstSeen

object

When this email was first observed

Show firstSeen properties

human

string

Human-readable time (e.g., “3 months ago”)

timestamp

number

Unix timestamp

iso

string

ISO 8601 formatted date

userActivity

string

User activity level (“high”, “medium”, “low”, “none”)

overallScore

number

Combined quality score (0-100, higher = better)

Associated Data

associatedNames

string[]

Names associated with this email address

associatedPhoneNumbers

string[]

Phone numbers associated with this email

Request Information

message

string

Human-readable status message

requestId

string

Unique identifier for this verification request

Response Example

{
  "success": true,
  "result": {
    "valid": true,
    "disposable": false,
    "catchAll": false,
    "fraudScore": 12,
    "spamTrapScore": "none",
    "recentAbuse": false,
    "leaked": false,
    "frequentComplainer": false,
    "deliverability": "high",
    "dnsValid": true,
    "mxRecords": true,
    "smtpScore": 3,
    "sanitizedEmail": "[email protected]",
    "honeypot": false,
    "generic": false,
    "common": false,
    "domainAge": {
      "human": "15 years",
      "timestamp": 1234567890,
      "iso": "2009-02-13T23:31:30Z"
    },
    "firstSeen": {
      "human": "2 years ago",
      "timestamp": 1609459200,
      "iso": "2021-01-01T00:00:00Z"
    },
    "userActivity": "high",
    "overallScore": 88,
    "associatedNames": ["John Doe"],
    "associatedPhoneNumbers": [],
    "message": "Success",
    "requestId": "abc123xyz"
  }
}

Error Responses

400

Invalid email address

{
  "success": false,
  "error": "Invalid email address"
}

400

Invalid email format

{
  "success": false,
  "error": "Invalid email format"
}

500

Verification failed

{
  "success": false,
  "error": "Verification failed"
}

Configuration

Set this environment variable to enable email verification:

# Required: IPQualityScore API key
IPQUALITYSCORE_API_KEY=your_ipqs_api_key

Get an IPQualityScore API key at https://www.ipqualityscore.com/

Source Code Reference

API Route: source/app/api/email/verify/route.ts:7
Email Verification: source/lib/email/verify.ts
Type Definitions: source/lib/email/types.ts

Risk Assessment Guide

Fraud Score Interpretation

0-25 (Low Risk)
26-50 (Medium Risk)
51-75 (High Risk)
76-100 (Critical Risk)

Safe to accept

High deliverability
No abuse history
Established domain
Valid MX records

Best Practices

Rate Limits: IPQualityScore has API rate limits. Cache results and avoid redundant checks.

Recommendations

Cache results: Store verification results to reduce API calls
Gradual validation: Check format first, then DNS, then full verification
User-friendly errors: Don’t expose technical details to end users
Typo suggestions: Use suggestedDomain to help users fix mistakes
Privacy compliance: Inform users about verification checks

Example Implementation

interface EmailRiskAssessment {
  email: string;
  isValid: boolean;
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  reasons: string[];
}

async function assessEmail(email: string): Promise<EmailRiskAssessment> {
  const response = await fetch('/api/email/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email })
  });

  const { result } = await response.json();
  
  // Determine risk level
  let riskLevel: 'low' | 'medium' | 'high' | 'critical';
  if (result.fraudScore < 25) riskLevel = 'low';
  else if (result.fraudScore < 50) riskLevel = 'medium';
  else if (result.fraudScore < 75) riskLevel = 'high';
  else riskLevel = 'critical';
  
  // Build list of risk factors
  const reasons: string[] = [];
  if (result.disposable) reasons.push('Disposable email provider');
  if (result.recentAbuse) reasons.push('Recent abuse reports');
  if (result.leaked) reasons.push('Found in data breaches');
  if (result.honeypot) reasons.push('Honeypot trap detected');
  if (result.spamTrapScore !== 'none') reasons.push('Potential spam trap');
  if (!result.mxRecords) reasons.push('No valid MX records');
  if (result.deliverability === 'undeliverable') reasons.push('Undeliverable');
  
  return {
    email: result.sanitizedEmail,
    isValid: result.valid && riskLevel !== 'critical',
    riskLevel,
    reasons
  };
}

// Usage
const assessment = await assessEmail('[email protected]');

if (assessment.riskLevel === 'critical') {
  console.error('Email rejected:', assessment.reasons);
} else if (assessment.riskLevel === 'high') {
  console.warn('Email flagged:', assessment.reasons);
} else {
  console.log('Email accepted');
}

Endpoints

Email Verification API

Overview

Endpoint

Request

Headers

Body Parameters

Request Example

Response

Core Validation

Risk Scoring

Deliverability

Email Details

Domain Information

Account Information

Associated Data

Request Information

Response Example

Error Responses

Configuration

Source Code Reference

Risk Assessment Guide

Fraud Score Interpretation

Best Practices

Recommendations

Example Implementation

Build docs developers (and LLMs) love

Endpoints

​Overview

​Endpoint

​Request

​Headers

​Body Parameters

​Request Example

​Response

​Core Validation

​Risk Scoring

​Deliverability

​Email Details

​Domain Information

​Account Information

​Associated Data

​Request Information

​Response Example

​Error Responses

​Configuration

​Source Code Reference

​Risk Assessment Guide

​Fraud Score Interpretation

​Best Practices

​Recommendations

​Example Implementation

Build docs developers (and LLMs) love

Overview

Endpoint

Request

Headers

Body Parameters

Request Example

Response

Core Validation

Risk Scoring

Deliverability

Email Details

Domain Information

Account Information

Associated Data

Request Information

Response Example

Error Responses

Configuration

Source Code Reference

Risk Assessment Guide

Fraud Score Interpretation

Best Practices

Recommendations

Example Implementation