Skip to main content
POST
POST /validate

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
X-Project-Id
string
required
Your project ID

Request Body

email
string
required
The email address to validate (will be normalized to lowercase)
fingerprintHash
string
Device fingerprint hash for client-side validation and device tracking.
sdkVersion
string
SDK version identifier (automatically included by SDKs)
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.
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.
validations
object
Optional override for which validations to run and their actions (allow/flag/block)
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
message
string | null
required
Human-friendly error message when the recommendation is flag or block (e.g. “Please use a permanent email address, not a temporary one.”). null when the recommendation is allow.
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

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

Example with Signals

Error Responses

All errors return an error object with HTTP status codes.

Rate Limits

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:

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
  • Option 1: Use the message field to display user-friendly error messages directly
  • Option 2: Check individual checks for custom error messages and business logic
  • Don’t expose internal validation details (signals, metadata) to users
  • Consider allowing flagged emails with additional verification
  • Set up alerts when approaching quota limits
  • Upgrade plan before hitting limits

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