Verifying Emails

The verification endpoint is the core of TinyValidator. It analyzes an email address and returns detailed information about its validity and risk factors.

Endpoint

You can pass the email as a query parameter or path parameter:

GET https://tinyvalidator.com/api/v1/[email protected]
GET https://tinyvalidator.com/api/v1/verify/[email protected]

Request

Email Parameter

The email can be provided in two ways:

Method	Example
Query parameter	/api/v1/[email protected]
Path parameter	/api/v1/verify/[email protected]

Authentication

You can authenticate requests in two ways:

Option 1: Authorization Header (Recommended)

curl "https://tinyvalidator.com/api/v1/verify/[email protected]" \
  -H "Authorization: Bearer your_api_key"

Option 2: Query Parameter

curl "https://tinyvalidator.com/api/v1/verify/[email protected]?api_key=your_api_key"

Response

Success Response (200)

{
  "email": "[email protected]",
  "valid": true,
  "score": 85,
  "deliverability": "high",
  "disposable": false,
  "role_account": false,
  "catch_all": false,
  "free_email": false,
  "syntax_valid": true,
  "domain_valid": true,
  "mailbox_valid": true,
  "provider": "google",
  "mx_host": "gmail-smtp-in.l.google.com.",
  "suggestion": null,
  "dns": null
}

Response Fields

Core Fields

Field	Type	Description
email	string	The normalized email that was verified
valid	boolean	Overall validity (domain exists and not disposable)
score	number	Quality score from 0-100
deliverability	string	Rating: high, medium, low, or risky
suggestion	string | null	Suggested correction for typos (e.g., gmail.con → gmail.com)

Validation Checks

Field	Type	Description
syntax_valid	boolean	Email follows RFC 5322 format
domain_valid	boolean	Domain has valid MX records
mailbox_valid	boolean	Mailbox verified to exist

Risk Flags

Field	Type	Description
disposable	boolean	Uses a disposable/temporary email service
catch_all	boolean	Domain accepts all addresses (can't verify specific mailbox)
role_account	boolean	Generic address like info@, support@, admin@
free_email	boolean	Uses a free email provider (Gmail, Yahoo, etc.)

Metadata

Field	Type	Description
provider	string | null	Detected email provider (google, microsoft, yahoo, etc.)
mx_host	string | null	Primary MX host for the domain
dns	object | null	DNS security info for non-major providers

DNS Object (when present)

Field	Type	Description
has_spf	boolean	Domain has SPF record
has_dmarc	boolean	Domain has DMARC record
dmarc_policy	string | null	DMARC policy: none, quarantine, or reject

Score Calculation

The quality score (0-100) evaluates multiple factors including syntax validity, domain reputation, mailbox verification, and risk indicators.

Deliverability Ratings

Rating	Score Range	Meaning
high	80-100	Safe to send, high confidence
medium	50-79	Likely deliverable, some risk
low	25-49	Risky, may bounce
risky	0-24	Do not send

For more details on how to interpret scores, see Understanding Scores.

Code Examples

TypeScript

interface VerifyResponse {
  email: string;
  valid: boolean;
  score: number;
  deliverability: 'high' | 'medium' | 'low' | 'risky';
  disposable: boolean;
  role_account: boolean;
  catch_all: boolean;
  free_email: boolean;
  syntax_valid: boolean;
  domain_valid: boolean;
  mailbox_valid: boolean;
  provider: string | null;
  mx_host: string | null;
  suggestion: string | null;
  dns: {
    has_spf: boolean;
    has_dmarc: boolean;
    dmarc_policy: 'none' | 'quarantine' | 'reject' | null;
  } | null;
}

async function verifyEmail(email: string): Promise<VerifyResponse> {
  const response = await fetch(
    `https://tinyvalidator.com/api/v1/verify?email=${encodeURIComponent(email)}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TINYVALIDATOR_API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Verification failed: ${response.status}`);
  }

  return response.json();
}

// Usage
const result = await verifyEmail('[email protected]');

if (!result.valid) {
  console.log('Invalid email');
} else if (result.suggestion) {
  console.log(`Did you mean: ${result.suggestion}?`);
} else if (result.disposable) {
  console.log('Warning: Disposable email detected');
}

Form Validation Example

async function handleSignup(formData: FormData) {
  const email = formData.get('email') as string;
  const result = await verifyEmail(email);

  // Check for typos first
  if (result.suggestion) {
    return {
      error: `Did you mean ${result.suggestion}?`,
      suggestion: result.suggestion
    };
  }

  if (!result.valid) {
    return { error: 'Please enter a valid email address' };
  }

  if (result.disposable) {
    return { error: 'Please use a permanent email address' };
  }

  if (result.deliverability === 'risky') {
    return { error: 'This email address appears to be invalid' };
  }

  // Proceed with signup...
}

Error Handling

Common Errors

Status	Error	Description
400	invalid_request	Missing or invalid email parameter
401	unauthorized	Invalid or missing API key
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error

Error Response Format

{
  "error": "invalid_request",
  "message": "Invalid request",
  "errors": [
    {
      "path": ["email"],
      "message": "Invalid email format"
    }
  ]
}

Best Practices

1. Verify at signup - Catch bad emails before they enter your database
2. Show suggestions - If suggestion is returned, prompt the user to confirm
3. Handle disposables - Decide if you want to allow temporary emails
4. Use deliverability - The deliverability rating is easier to act on than raw scores
5. Cache results - Avoid re-verifying the same email repeatedly
6. Graceful degradation - Have a fallback if the API is unavailable