Validation Endpoint

POST /validate

Validates an email address using comprehensive checks including syntax, domain/MX records, disposable detection, SMTP verification, and AI-powered risk scoring.

Endpoint

POST https://api.spamidate.com/validate

Authentication

Required. All requests must include your secret API key (sk_live_...) for server-side validation.

See the Authentication Guide for complete details on the two-key system, scopes, and IP whitelisting.

Request

Headers

Header	Required	Description
`X-API-Key`	Yes*	Your secret API key starting with `sk_live_` (recommended method)
`Authorization`	Yes*	Alternative: `Bearer sk_live_...` format
`Content-Type`	Yes	Must be `application/json`

*One authentication method required (either X-API-Key or Authorization header)

Body Parameters

{
  "email": "user@example.com",
  "options": {
    "quickMode": false,
    "skipCatchAll": false
  }
}

Parameter	Type	Required	Description
`email`	string	Yes	Email address to validate (max 254 characters)
`options`	object	No	Validation options
`options.quickMode`	boolean	No	Skip slower checks (SMTP, catch-all). Default: `false`
`options.skipCatchAll`	boolean	No	Skip catch-all detection. Default: `false`

Response

Success Response (200 OK)

{
  "isValid": true,
  "email": "user@example.com",
  "score": 95,
  "severity": "valid",
  "checks": {
    "syntax": {
      "passed": true,
      "check": "syntax",
      "message": "Valid email format",
      "metadata": {
        "localPart": "user",
        "domain": "example.com"
      }
    },
    "domain": {
      "passed": true,
      "check": "domain",
      "message": "Domain exists and has MX records",
      "metadata": {
        "hasMX": true,
        "mxRecords": ["mx1.example.com", "mx2.example.com"]
      }
    },
    "disposable": {
      "passed": true,
      "check": "disposable",
      "message": "Not a disposable email provider"
    },
    "roleBased": {
      "passed": true,
      "check": "roleBased",
      "message": "Not a role-based address",
      "metadata": {
        "isRole": false,
        "confidence": "high"
      }
    },
    "smtp": {
      "passed": true,
      "check": "smtp",
      "message": "Mailbox exists and can receive mail",
      "metadata": {
        "smtpResponse": "250 OK"
      }
    },
    "catchAll": {
      "passed": true,
      "check": "catchAll",
      "message": "Not a catch-all domain",
      "metadata": {
        "isCatchAll": false
      }
    }
  },
  "recommendations": [
    "Email is valid and safe to use",
    "High deliverability score"
  ],
  "metadata": {
    "processingTime": 45,
    "timestamp": "2025-01-15T10:30:00Z",
    "ipAddress": "203.0.113.42",
    "country": "US"
  }
}

Response Fields

isValid

Type: boolean

Overall validation result. true if the email passed all critical checks, false otherwise.

Type: string

The email address that was validated (normalized to lowercase).

score

Type: number (0-100)

AI-powered deliverability confidence score:

70-100: Valid, high deliverability
40-69: Warning, moderate risk
0-39: Invalid, high bounce risk

severity

Type: string

Risk classification based on score:

valid: Safe to use (score ≥ 70)
warning: Proceed with caution (score 40-69)
invalid: Not recommended (score < 40)

checks

Type: object

Individual validation check results. Each check contains:

passed (boolean): Whether the check succeeded
check (string): Check identifier
message (string): Human-readable result
metadata (object): Additional check-specific data

Available checks:

syntax: RFC 5322 compliance
domain: DNS and MX record verification
disposable: Temporary email detection
roleBased: Generic address detection (info@, support@)
smtp: Mailbox existence verification
catchAll: Catch-all domain detection

recommendations

Type: array<string>

Actionable advice based on validation results.

metadata

Type: object

Request metadata including:

processingTime (number): Milliseconds taken
timestamp (string): ISO 8601 timestamp
ipAddress (string): Request origin IP
country (string): ISO 3166-1 alpha-2 country code

Examples

curl -X POST https://api.spamidate.com/validate \
  -H "X-API-Key: sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@company.com"
  }'

{
  "isValid": true,
  "score": 98,
  "severity": "valid",
  "email": "john.doe@company.com",
  "checks": {
    "syntax": { "passed": true, "message": "Valid email format" },
    "domain": { "passed": true, "message": "Domain exists with MX records" },
    "disposable": { "passed": true, "message": "Not disposable" },
    "smtp": { "passed": true, "message": "Mailbox exists" }
  }
}

curl -X POST https://api.spamidate.com/validate \
  -H "X-API-Key: sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "temp@tempmail.com"
  }'

{
  "isValid": false,
  "score": 15,
  "severity": "invalid",
  "email": "temp@tempmail.com",
  "checks": {
    "syntax": { "passed": true, "message": "Valid email format" },
    "domain": { "passed": true, "message": "Domain exists" },
    "disposable": { "passed": false, "message": "Disposable email provider detected" }
  },
  "recommendations": [
    "Email is from a disposable provider",
    "Consider rejecting or requiring additional verification"
  ]
}

curl -X POST https://api.spamidate.com/validate \
  -H "X-API-Key: sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "not-an-email"
  }'

{
  "isValid": false,
  "score": 0,
  "severity": "invalid",
  "email": "not-an-email",
  "checks": {
    "syntax": { "passed": false, "message": "Invalid email format: missing @ symbol" }
  },
  "recommendations": [
    "Email format is invalid",
    "Check for typos or formatting errors"
  ]
}

curl -X POST https://api.spamidate.com/validate \
  -H "X-API-Key: sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "options": {
      "quickMode": true
    }
  }'

Quick mode skips SMTP and catch-all checks for faster response (~20-30ms). Useful for high-volume scenarios where basic validation is sufficient.

Error Responses

400 Bad Request

Invalid request body or parameters.

{
  "error": "Bad Request",
  "message": "Invalid email format in request body",
  "field": "email"
}

401 Unauthorized

Missing or invalid API key.

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

429 Too Many Requests

Rate limit exceeded. Limits vary by subscription tier (Growth: 10/min, Pro: 23/min, Business: 93/min, Scale: 289/min, Enterprise: 694/min).

{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded your rate limit of 93 requests per minute",
  "retryAfter": 45,
  "limit": 93,
  "remaining": 0,
  "reset": 1642521600
}

Note: The hybrid overage model allows 20% buffer (100-120% of quota) before this error occurs.

500 Internal Server Error

Server error (rare, automatically reported).

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again.",
  "requestId": "req_abc123xyz"
}

Rate Limit Headers

All responses include rate limit information in the headers:

X-RateLimit-Limit: 93
X-RateLimit-Remaining: 88
X-RateLimit-Reset: 1642521600

X-RateLimit-Limit: Maximum requests allowed per minute for your tier
X-RateLimit-Remaining: Requests left in current minute
X-RateLimit-Reset: Unix timestamp when the limit resets

Hybrid Overage Model: You get a 20% buffer (100-120% of your quota) before receiving a 429 error. See the Rate Limiting documentation for details.

Next Steps

Review the Authentication Guide for security features (scopes, IP whitelisting, key rotation)
Learn about Quick Start to integrate Spamidate in minutes
Understand the validation pipeline and scoring system in the response examples above
Test the API interactively on the home page using the live terminal