Skip to main content
POST
https://api.vouch.expert
/
validate
POST /validate
curl --request POST \
  --url https://api.vouch.expert/validate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Project-Id: <x-project-id>' \
  --data '
{
  "email": "<string>",
  "fingerprintHash": "<string>",
  "sdkVersion": "<string>",
  "ip": "<string>",
  "userAgent": "<string>",
  "validations": {}
}
'
{
  "error": "Invalid email format"
}

​
Overview

The /validate endpoint is the core of Vouch’s API. It performs comprehensive email validation including syntax checking, disposable email detection, MX verification, and device fingerprinting.
You can use either the versioned endpoint /v1/validate or the latest endpoint /validate

​
Authentication

​
Authorization
string
required
Bearer token with your API key
Authorization: Bearer your_api_key_here
​
X-Project-Id
string
required
Your project ID
X-Project-Id: your_project_id

​
Request Body

​
email
string
required
The email address to validate (will be normalized to lowercase)
"[email protected]"
​
fingerprintHash
string
Device fingerprint hash for client-side validation and device tracking.
"abc123def456789..."
​
sdkVersion
string
SDK version identifier (automatically included by SDKs)
"@vouch/[email protected]"
​
ip
string
Server-side only: Override client IP address for validation. If not provided, the API will use the request’s IP address from headers (CF-Connecting-IP or X-Forwarded-For).Only available when using a server API key.
"192.168.1.1"
​
userAgent
string
Server-side only: Override User-Agent for validation. If not provided, the API will use the request’s User-Agent header.Only available when using a server API key.
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
​
validations
object
Optional override for which validations to run and their actions (allow/flag/block)
{
  "syntax": "block",
  "disposable": "block",
  "mx": "block",
  "smtp": "flag",
  "catchall": "flag",
  "roleEmail": "flag",
  "alias": "flag",
  "device": "flag",
  "ip": "flag"
}
The SDKs automatically construct the request body. When using the API directly, ensure all required fields are included.

​
Response

​
checks
object
required
Individual validation check results. Each check contains:Available checks include: syntax, disposable, mx, roleEmail, alias, device, ip
​
metadata
object
required
Validation metadata
​
recommendation
string
required
Overall recommendation based on all checks: allow, flag, or block
​
signals
array
required
Array of signal identifiers detected during validation (e.g., ["disposable_email", "vpn_detected"])

​
Example Request

curl --request POST \
  --url https://api.vouch.expert/validate \
  --header 'Authorization: Bearer your_server_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Project-Id: your_project_id' \
  --data '{
    "email": "[email protected]",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'
Client-side requests: Use the JavaScript/React SDKs which automatically include device fingerprinting in the fingerprint field.Server-side requests: Only provide ip and userAgent if you need to override the request’s headers.

​
Example Response

{
  "checks": {
    "syntax": {
      "pass": true,
      "latency": 0.8
    },
    "disposable": {
      "pass": true,
      "latency": 12.3
    },
    "mx": {
      "pass": true,
      "latency": 45.2
    },
    "roleEmail": {
      "pass": true,
      "latency": 0.5
    },
    "alias": {
      "pass": true,
      "latency": 0.3
    },
    "device": {
      "pass": true,
      "latency": 15.7
    },
    "ip": {
      "pass": true,
      "latency": 8.4
    }
  },
  "metadata": {
    "fingerprintHash": "abc123def456789",
    "previousSignups": 0,
    "totalLatency": 83.2
  },
  "recommendation": "allow",
  "signals": []
}

​
Example with Signals

{
  "checks": {
    "syntax": {
      "pass": true,
      "latency": 0.8
    },
    "disposable": {
      "pass": false,
      "latency": 12.3
    },
    "mx": {
      "pass": true,
      "latency": 45.2
    },
    "device": {
      "pass": false,
      "latency": 15.7
    },
    "ip": {
      "pass": false,
      "latency": 8.4
    }
  },
  "metadata": {
    "fingerprintHash": "abc123def456789",
    "previousSignups": 3,
    "totalLatency": 82.4
  },
  "recommendation": "block",
  "signals": [
    "disposable_email",
    "device_reuse",
    "device_seen_3_times",
    "vpn_detected"
  ]
}

​
Error Responses

All errors return an error object with HTTP status codes. 
{
  "error": "Invalid email format"
}

​
Rate Limits

Key TypeRate LimitWindow
Client Key1,000 requestsPer hour
Server Key5,000 requestsPer hour
Rate limits are per project. If you exceed the limit, you’ll receive a 429 error with a retryAfter value in seconds.

​
Quota Management

Each plan includes a monthly validation quota. Track your usage in the dashboard or via the response headers: 
X-Quota-Limit: 10000
X-Quota-Used: 2345
X-Quota-Remaining: 7655
X-Quota-Reset: 2024-01-01T00:00:00Z

​
Best Practices

  • Client keys for browser/mobile apps (includes automatic fingerprinting)
  • Server keys for backend validation (can override IP/User-Agent)
  • Never expose server keys in client-side code
  • block: Reject the signup immediately
  • flag: Allow signup but mark for review, or require additional verification
  • allow: Proceed normally
  • Cache validation results for repeated validations of the same email
  • Set TTL based on your use case (e.g., 24 hours)
  • Invalidate cache if user changes email
  • Show specific error messages (e.g., “Please use a permanent email address”)
  • Don’t expose internal validation details to users
  • Consider allowing flagged emails with additional verification
  • Set up alerts when approaching quota limits
  • Upgrade plan before hitting limits
  • Use test keys during development

​
Next Steps

Validation Types

Learn about each validation check

Error Handling

Handle errors gracefully

Use SDKs

Use our SDKs for easier integration

Best Practices

Production optimization tips