StopReg API Documentation

Getting Started with StopReg

StopReg is a powerful email validation API that helps you detect and block disposable, temporary, and fake email addresses in real-time. This documentation will guide you through integrating StopReg into your application to protect your platform from spam, fraud, and abuse.

What is StopReg?

StopReg provides businesses and individuals with tools and resources for detecting and blocking disposable email providers. Our API validates email addresses instantly (typically within milliseconds), allowing you to block disposable emails during signup, checkout, or form submission.

Key Features

Real-time Validation: Instant email checking with millisecond response times
Comprehensive Database: Over 124,000 disposable email domains in our database
Privacy-Focused: We don't store full email addresses - only check the domain part
Easy Integration: Simple REST API that works with any programming language
Whitelisting Support: Whitelist trusted domains to ensure legitimate users are never blocked

Quick Start

To get started with StopReg, you'll need:

Create an account at stopreg.com
Get your API token from your dashboard
Make your first API call to validate an email address

The API endpoint is simple and secure. You'll use a GET request with your API token in the header and the email/domain in the query string. Continue reading the next sections to learn about authentication, endpoints, and code examples.

API Authentication

StopReg uses API token-based authentication. Your API token is unique to your account and should be kept secure. Never share your API token publicly or commit it to version control systems.

Getting Your API Token

Log in to your StopReg dashboard
Navigate to the API section or locate the API token on your Dashboard home
Copy your API token (you can regenerate it at any time if needed)

Using Your API Token

We recommend using the x-api-token header for all requests. This keeps your token out of URL logs and follows industry standards.

Headers:
  x-api-token: YOUR_API_TOKEN

Security Best Practices

Keep it Secret: Treat your API token like a password - never expose it in client-side code
Use Environment Variables: Store your API token in environment variables, not in your source code
Regenerate if Compromised: If you suspect your token has been exposed, regenerate it immediately from your dashboard
Server-Side Only: Always make API calls from your server-side code, never from the browser

Rate Limits

Rate limits depend on your subscription plan. Free trial accounts have limited requests per day, while paid plans offer higher limits or unlimited requests. Check your dashboard for your current rate limit status.

API Endpoints

StopReg provides a simple REST API endpoint for email validation. All endpoints use HTTPS and return JSON responses.

Email Verification

Endpoint:

GET https://api.stopreg.com/api/v1/verify/email/{email}

Domain Verification

Endpoint:

GET https://api.stopreg.com/api/v1/verify/domain/{domain}

Path Parameters

{email} (string, required for /email): The email address to validate.
{domain} (string, required for /domain): The domain name to validate (e.g., example.com).

Request Examples

Email Verification

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

Headers:
  x-api-token: YOUR_API_TOKEN

Domain Verification

GET https://api.stopreg.com/api/v1/verify/domain/example.com

Headers:
  x-api-token: YOUR_API_TOKEN

Response Format

The API returns a JSON response with the following structure:

{
  "status": 200,
  "message": "success",
  "description": "Check successful",
  "data": {
    "input": {
      "email": "[email protected]",
      "normalized": "[email protected]",
      "suggestion": null
    },
    "domain": {
      "root": "example.com",
      "is_subdomain": false,
      "provider": null
    },
    "mail_server": {
      "mx_found": true,
      "mx_records": [
        { "hostname": "aspmx.l.google.com", "priority": 1 },
        { "hostname": "alt1.aspmx.l.google.com", "priority": 5 },
        { "hostname": "alt2.aspmx.l.google.com", "priority": 10 }
      ],
      "mx_provider": [
        {
          "slug": "zoho corporation",
          "service_type": "mailbox",
          "grade": "professional"
        },
        {
          "slug": "namecheap.com",
          "service_type": "hosting",
          "grade": "standard"
        }
      ]
    },
    "classification": {
      "is_disposable": false,
      "is_relay": false,
      "is_unresolved": false,
      "is_public": true,
      "is_role_based": false,
      "is_alias": false
    },
    "policy": {
      "blocklisted": "Login to configure the blocklist",
      "allowlisted": "Login to configure the allowlist"
    }
  }
}

Response Fields

The API response is structured into several nested objects. Below is a detailed technical reference for each field in the payload.

Top-Level Fields

Field	Type	Description
status Integer	200, 400, 401, etc.	The HTTP status code. Indicates the overall success or failure of the request.
message String	"success" \| "error"	A short string indicating the result state of the API operation.
description String	Text	A human-readable summary of the verification result or the specific reason for an error.
data Object	Payload	The container for all verification intelligence. Details are broken down in the sections below.

Domain & Registry Analytics (data.domain)

Field	Type	Description
root String	Value	The root domain extracted from your input (e.g., `google.com`).
is_subdomain Boolean	true / false	`true` if the input contained a subdomain prefix (e.g., `mail.google.com`); `false` if the input was already a root domain.
provider String \| null	Host	The identified provider for this domain. Only populated for disposable, relay, or free email providers (e.g., `"Google"`, `"Mailinator"`). Returns `null` for domains that do not match any known provider classification.

Input Intelligence (data.input)

Field	Type	Description
email \| domain String	Raw Value	The original input provided in your request. Use this to map the response back to your local records.
normalized String	Canonical	The standardized version of your input. This value is lowercased, trimmed, and stripped of sub-addressing (e.g., user+tag@ becomes user@).
suggestion String	Correction	If a common typo is detected (e.g., gnail.com), this provides the corrected domain (gmail.com). Returns `null` if no correction is needed.

Infrastructure Analytics (data.mail_server)

Field	Type	Description
mx_found Boolean	Status	`true` if valid Mail Exchange (MX) records were found for the domain. If `false`, the email is likely undeliverable.
mx_records Array	List	An ordered array of MX records resolved from the domain's DNS settings, sorted by priority (lowest number = highest precedence). Each entry contains: hostname: The mail exchange hostname (e.g., `"aspmx.l.google.com"`). priority: The DNS priority value — lower numbers receive mail first.
mx_provider Array	Providers	Multi-Provider Intelligence. A prioritized list of all infrastructure providers detected behind the email (e.g., Zoho + Namecheap). Contains: slug: Identifier (e.g., "zoho corporation"). service_type: `mailbox`, `hosting`, `relay`, or `disposable`. grade: Professionalism tier (e.g., `professional`).

Strategic Classification (data.classification)

Field	Type	Description
is_disposable Boolean	High Risk	Critical Flag. `true` if the domain belongs to a temporary, throwaway, or 10-minute mail provider. High correlation with fraud.
is_relay Boolean	Low Risk	`true` if the provider is a forwarding service or alias system (e.g., iCloud Hide My Email). Common among privacy-conscious users.
is_unresolved Boolean	Neutral	Zero-Trust Flag. `true` for unknown, non-major domains that proxy through professional mail hosts. High correlation with "Stealth Disposable" providers.
is_public Boolean	Neutral	`true` for common free consumers providers (Gmail, Outlook, Yahoo). Generally safe for B2C registrations.
is_role_based Boolean	Caution	`true` for address intended for groups (e.g., admin@, support@). Not ideal for personal account signups.
is_alias Boolean	Low Risk	`true` if sub-addressing was detected (e.g., [email protected]). Often used to track source of signups.

Custom Policy Logic (data.policy)

Field	Type	Description
blocklisted Boolean	Custom	`true` if the input matches a domain or email explicitly blocked in your StopReg Dashboard.
allowlisted Boolean	Custom	`true` if the input matches a trusted domain in your Dashboard, bypassing all disposable checks.

Error Responses

If an error occurs, the API returns a JSON response with standardized error codes:

{
  "status": 401,
  "message": "error",
  "description": "The provided API token is invalid.",
  "data": {
    "error": "invalid_token"
  }
}

HTTP Status Codes

200 OK: Request successful
400 Bad Request: Invalid parameters (e.g., invalid_email, invalid_domain)
401 Unauthorized: Authentication issues (missing_token, invalid_token, token_expired)
429 Too Many Requests: Rate limit exceeded (rate_limited) or quota exhausted (token_exhausted)
500 Internal Server Error: Unexpected server error

Official Libraries

We provide official SDKs for popular programming languages and frameworks. For a detailed comparison and quick-start guide for all available libraries, visit our Official Libraries Hub.

Node.js SDK (NPM)

Our Node.js SDK is designed for high-performance and zero-dependency security. It includes full TypeScript support and robust error handling.

npm install stopreg

Email Verification:

import { StopReg } from 'stopreg';

const client = new StopReg({ apiToken: 'YOUR_API_TOKEN' });

try {
  const response = await client.verification.checkEmail('[email protected]');
  
  // View the full intelligence payload
  console.log(response);

  const isBlocked = response.data.classification.is_disposable || response.data.policy.blocklisted === true;

  if (isBlocked) {
    console.log('This email is blocked.');
  }
} catch (error) {
  console.error(error.message);
}

Domain Verification:

import { StopReg } from 'stopreg';

const client = new StopReg({ apiToken: 'YOUR_API_TOKEN' });

try {
  const response = await client.verification.checkDomain('test.com');
  
  // View the full intelligence payload
  console.log(response);

  const isBlocked = response.data.classification.is_disposable || response.data.policy.blocklisted === true;

  if (isBlocked) {
    console.log('This domain is blocked.');
  }
} catch (error) {
  console.error(error.message);
}

Laravel SDK (Composer)

The official Laravel package integrates seamlessly with the Laravel Service Container and provides a clean Facade for instant verification.

composer require stopreg/laravel

Email Verification:

use StopReg\Laravel\Facades\StopReg;

try {
    $result = StopReg::checkEmail('[email protected]');
    
    // Dump the result to see full intelligence data
    dd($result);

    $isBlocked = $result['data']['classification']['is_disposable'] || ($result['data']['policy']['blocklisted'] ?? false) === true;

    if ($isBlocked) {
        return back()->withErrors(['email' => 'This email is not allowed.']);
    }
} catch (StopRegException $e) {
    // Handle error
}

Domain Verification:

use StopReg\Laravel\Facades\StopReg;

try {
    $result = StopReg::checkDomain('test.com');

    // Dump the result to see full intelligence data
    dd($result);

    $isBlocked = $result['data']['classification']['is_disposable'] || ($result['data']['policy']['blocklisted'] ?? false) === true;

    if ($isBlocked) {
        return back()->withErrors(['domain' => 'This domain is not allowed.']);
    }
} catch (StopRegException $e) {
    // Handle error
}

Code Examples

Here are code examples for integrating StopReg API in various programming languages. Replace YOUR_API_TOKEN with your actual API token.

JavaScript (Node.js)

const apiToken = 'YOUR_API_TOKEN';
const email = '[email protected]';

const response = await fetch(`https://api.stopreg.com/api/v1/verify/email/${email}`, {
    method: 'GET',
    headers: {
      'x-api-token': apiToken,
    }
  }
);

const body = await response.json();
console.log(body);

const isBlocked = body.data?.classification?.is_disposable || body.data?.policy?.blocklisted === true;

if (isBlocked) {
  console.log('Access is blocked');
}

Python

import requests

url = f'https://api.stopreg.com/api/v1/verify/email/{email}'

response = requests.get(
    url,
    headers={'x-api-token': api_token}
)

body = response.json()
print(body)

is_blocked = body.get('data', {}).get('classification', {}).get('is_disposable') or \
             body.get('data', {}).get('policy', {}).get('blocklisted') is True

if is_blocked:
    print('Access is blocked')

PHP

<?php

$apiToken = 'YOUR_API_TOKEN';
$email = '[email protected]';

$url = "https://api.stopreg.com/api/v1/verify/email/" . urlencode($email);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-token: ' . $apiToken
]);

$response = curl_exec($ch);
$body = json_decode($response, true);

curl_close($ch);

$isDisposable = $body['data']['classification']['is_disposable'] ?? false;
$isBlocklisted = ($body['data']['policy']['blocklisted'] ?? false) === true;

if ($isDisposable || $isBlocklisted) {
    echo 'Access is blocked';
}
?>

cURL

curl -X GET \
  "https://api.stopreg.com/api/v1/verify/email/[email protected]" \
  -H "x-api-token: YOUR_API_TOKEN"

Integration in Registration Forms

When integrating StopReg into your registration or signup forms, validate the email address before allowing the user to complete registration. If data.classification.is_disposable is true, show an error message asking the user to use a valid email address.

Best Practices & Troubleshooting

Follow these best practices to ensure optimal performance and reliability when using the StopReg API.

Best Practices

Validate on Server-Side: Always perform email validation on your server, never in client-side JavaScript. This protects your API token and ensures security.
Handle Errors Gracefully: Implement proper error handling for network failures, rate limits, and API errors. Provide user-friendly error messages.
Cache Results When Appropriate: For frequently checked domains, consider caching results to reduce API calls and improve performance.
Use Whitelisting: Whitelist trusted corporate domains to prevent false positives and ensure legitimate users are never blocked.
Monitor Rate Limits: Keep track of your API usage to avoid hitting rate limits. Upgrade your plan if needed.
Validate Email Format First: Check basic email format before calling the API to save unnecessary requests.

Common Use Cases

Registration Forms: Validate emails during user signup to prevent fake accounts
Checkout Processes: Block disposable emails during e-commerce checkout
Free Trial Signups: Prevent abuse of free trial offers
Newsletter Subscriptions: Ensure quality email lists
Support Ticket Systems: Verify contact emails for support requests

Troubleshooting

API Returns Error

Verify your API token is correct and active
Check that the email parameter is properly URL-encoded
Ensure you're using the correct endpoint URL

Slow Response Times

Check your network connection
Verify you're using HTTPS (not HTTP)
Consider implementing request timeouts and retries

False Positives

Use the whitelist feature for trusted domains
Report false positives through your dashboard
Check if the domain is actually disposable before blocking

Recommended Validation Configurations

Below are common StopReg validation configurations that can be used depending on your registration requirements. Each configuration uses fields from the data.classification and data.mail_server objects in the API response.

1. Block Disposable Email Domains Only

Recommended if you want to block temporary and disposable email providers while allowing most legitimate users.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block disposable domains
if (classification.is_disposable) {
  throw new Error('Disposable email addresses are not allowed.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block disposable domains
if classification.get('is_disposable'):
    raise ValueError('Disposable email addresses are not allowed.')

# Allow relay emails           ✓
# Allow unresolved domains      ✓
# Allow public email providers  ✓
# Allow role-based emails       ✓
# Allow alias emails            ✓

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block disposable domains
if ($classification['is_disposable'] ?? false) {
    throw new Exception('Disposable email addresses are not allowed.');
}

// Allow relay emails           ✓
// Allow unresolved domains      ✓
// Allow public email providers  ✓
// Allow role-based emails       ✓
// Allow alias emails            ✓

2. Allow Public & Custom Domains

Recommended if you want to allow Gmail, Yahoo, Outlook, and custom business domains while blocking risky email types.

const result = await client.verification.checkEmail(email);
const { classification, mail_server } = result.data;

// Allow public email providers and custom domains
if (classification.is_disposable) {
  throw new Error('Disposable email addresses are not allowed.');
}
if (classification.is_relay) {
  throw new Error('Relay email addresses are not allowed.');
}
if (classification.is_alias) {
  throw new Error('Email aliases are not allowed.');
}
if (classification.is_role_based) {
  throw new Error('Role-based email addresses are not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
data = response.json()['data']
classification = data['classification']
mail_server = data['mail_server']

# Allow public email providers and custom domains
if classification.get('is_disposable'):
    raise ValueError('Disposable email addresses are not allowed.')
if classification.get('is_relay'):
    raise ValueError('Relay email addresses are not allowed.')
if classification.get('is_alias'):
    raise ValueError('Email aliases are not allowed.')
if classification.get('is_role_based'):
    raise ValueError('Role-based email addresses are not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Allow public email providers and custom domains
if ($classification['is_disposable'] ?? false) {
    throw new Exception('Disposable email addresses are not allowed.');
}
if ($classification['is_relay'] ?? false) {
    throw new Exception('Relay email addresses are not allowed.');
}
if ($classification['is_alias'] ?? false) {
    throw new Exception('Email aliases are not allowed.');
}
if ($classification['is_role_based'] ?? false) {
    throw new Exception('Role-based email addresses are not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

Alternative configuration:

const { classification, mail_server } = result.data;

// Block role and alias emails together
if (classification.is_role_based || classification.is_alias) {
  throw new Error('Role-based or alias email addresses are not allowed.');
}
if (classification.is_disposable || classification.is_relay) {
  throw new Error('This email type is not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

# Assumes data already fetched from API
classification = data['classification']
mail_server = data['mail_server']

# Block role and alias emails together
if classification.get('is_role_based') or classification.get('is_alias'):
    raise ValueError('Role-based or alias email addresses are not allowed.')
if classification.get('is_disposable') or classification.get('is_relay'):
    raise ValueError('This email type is not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
// Assumes $body already fetched from API
$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Block role and alias emails together
if (($classification['is_role_based'] ?? false) || ($classification['is_alias'] ?? false)) {
    throw new Exception('Role-based or alias email addresses are not allowed.');
}
if (($classification['is_disposable'] ?? false) || ($classification['is_relay'] ?? false)) {
    throw new Exception('This email type is not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

3. Allow Business Domains Only

Recommended for B2B platforms that only accept company or business email addresses.

const result = await client.verification.checkEmail(email);
const { classification, mail_server } = result.data;

// Allow only business/custom domains
// Block public email providers (Gmail, Yahoo, Outlook, etc.)
if (classification.is_public) {
  throw new Error('Please use your company email address.');
}
if (classification.is_disposable) {
  throw new Error('Disposable email addresses are not allowed.');
}
if (classification.is_relay) {
  throw new Error('Relay email addresses are not allowed.');
}
if (classification.is_role_based) {
  throw new Error('Role-based email addresses are not allowed.');
}
if (classification.is_alias) {
  throw new Error('Email aliases are not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
data = response.json()['data']
classification = data['classification']
mail_server = data['mail_server']

# Allow only business/custom domains
# Block public email providers (Gmail, Yahoo, Outlook, etc.)
if classification.get('is_public'):
    raise ValueError('Please use your company email address.')
if classification.get('is_disposable'):
    raise ValueError('Disposable email addresses are not allowed.')
if classification.get('is_relay'):
    raise ValueError('Relay email addresses are not allowed.')
if classification.get('is_role_based'):
    raise ValueError('Role-based email addresses are not allowed.')
if classification.get('is_alias'):
    raise ValueError('Email aliases are not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Allow only business/custom domains
// Block public email providers (Gmail, Yahoo, Outlook, etc.)
if ($classification['is_public'] ?? false) {
    throw new Exception('Please use your company email address.');
}
if ($classification['is_disposable'] ?? false) {
    throw new Exception('Disposable email addresses are not allowed.');
}
if ($classification['is_relay'] ?? false) {
    throw new Exception('Relay email addresses are not allowed.');
}
if ($classification['is_role_based'] ?? false) {
    throw new Exception('Role-based email addresses are not allowed.');
}
if ($classification['is_alias'] ?? false) {
    throw new Exception('Email aliases are not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

Alternative configuration:

const { classification, mail_server } = result.data;

// Allow only business domains
if (classification.is_public || classification.is_disposable || classification.is_relay) {
  throw new Error('Please use a business email address.');
}
if (classification.is_role_based || classification.is_alias) {
  throw new Error('Role-based or alias email addresses are not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

# Assumes data already fetched from API
classification = data['classification']
mail_server = data['mail_server']

# Allow only business domains
if classification.get('is_public') or classification.get('is_disposable') or classification.get('is_relay'):
    raise ValueError('Please use a business email address.')
if classification.get('is_role_based') or classification.get('is_alias'):
    raise ValueError('Role-based or alias email addresses are not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
// Assumes $body already fetched from API
$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Allow only business domains
if (($classification['is_public'] ?? false) || ($classification['is_disposable'] ?? false) || ($classification['is_relay'] ?? false)) {
    throw new Exception('Please use a business email address.');
}
if (($classification['is_role_based'] ?? false) || ($classification['is_alias'] ?? false)) {
    throw new Exception('Role-based or alias email addresses are not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

4. Allow Public Email Providers Only

Recommended if you only want to allow Gmail, Yahoo, Outlook, and other free public email providers.

const result = await client.verification.checkEmail(email);
const { classification, mail_server } = result.data;

// Allow public email providers only (Gmail, Yahoo, Outlook, etc.)
// Block business/custom domains
if (!classification.is_public) {
  throw new Error('Only public email providers (Gmail, Yahoo, Outlook) are accepted.');
}
if (classification.is_disposable) {
  throw new Error('Disposable email addresses are not allowed.');
}
if (classification.is_relay) {
  throw new Error('Relay email addresses are not allowed.');
}
if (classification.is_role_based) {
  throw new Error('Role-based email addresses are not allowed.');
}
if (classification.is_alias) {
  throw new Error('Email aliases are not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
data = response.json()['data']
classification = data['classification']
mail_server = data['mail_server']

# Allow public email providers only (Gmail, Yahoo, Outlook, etc.)
# Block business/custom domains
if not classification.get('is_public'):
    raise ValueError('Only public email providers (Gmail, Yahoo, Outlook) are accepted.')
if classification.get('is_disposable'):
    raise ValueError('Disposable email addresses are not allowed.')
if classification.get('is_relay'):
    raise ValueError('Relay email addresses are not allowed.')
if classification.get('is_role_based'):
    raise ValueError('Role-based email addresses are not allowed.')
if classification.get('is_alias'):
    raise ValueError('Email aliases are not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Allow public email providers only (Gmail, Yahoo, Outlook, etc.)
// Block business/custom domains
if (!($classification['is_public'] ?? false)) {
    throw new Exception('Only public email providers (Gmail, Yahoo, Outlook) are accepted.');
}
if ($classification['is_disposable'] ?? false) {
    throw new Exception('Disposable email addresses are not allowed.');
}
if ($classification['is_relay'] ?? false) {
    throw new Exception('Relay email addresses are not allowed.');
}
if ($classification['is_role_based'] ?? false) {
    throw new Exception('Role-based email addresses are not allowed.');
}
if ($classification['is_alias'] ?? false) {
    throw new Exception('Email aliases are not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

Alternative configuration:

const { classification, mail_server } = result.data;

// Allow public email providers
if (!classification.is_public || classification.is_disposable || classification.is_relay) {
  throw new Error('Only public email providers are accepted.');
}
if (classification.is_role_based || classification.is_alias) {
  throw new Error('Role-based or alias email addresses are not allowed.');
}
if (!mail_server.mx_found) {
  throw new Error('Email domain has no mail server.');
}

# Assumes data already fetched from API
classification = data['classification']
mail_server = data['mail_server']

# Allow public email providers
if not classification.get('is_public') or classification.get('is_disposable') or classification.get('is_relay'):
    raise ValueError('Only public email providers are accepted.')
if classification.get('is_role_based') or classification.get('is_alias'):
    raise ValueError('Role-based or alias email addresses are not allowed.')
if not mail_server.get('mx_found'):
    raise ValueError('Email domain has no mail server.')

<?php
// Assumes $body already fetched from API
$classification = $body['data']['classification'] ?? [];
$mailServer = $body['data']['mail_server'] ?? [];

// Allow public email providers
if (!($classification['is_public'] ?? false) || ($classification['is_disposable'] ?? false) || ($classification['is_relay'] ?? false)) {
    throw new Exception('Only public email providers are accepted.');
}
if (($classification['is_role_based'] ?? false) || ($classification['is_alias'] ?? false)) {
    throw new Exception('Role-based or alias email addresses are not allowed.');
}
if (!($mailServer['mx_found'] ?? false)) {
    throw new Exception('Email domain has no mail server.');
}

5. Block Relay Emails

Use this check to reject email addresses routed through relay or privacy-forwarding services such as Apple Hide My Email, SimpleLogin, or AnonAddy.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block relay emails
if (classification.is_relay) {
  throw new Error('Relay email addresses are not allowed.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block relay emails
if classification.get('is_relay'):
    raise ValueError('Relay email addresses are not allowed.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block relay emails
if ($classification['is_relay'] ?? false) {
    throw new Exception('Relay email addresses are not allowed.');
}

6. Block Unresolved Domains

Use this check to reject email addresses from domains that cannot be verified — unknown registrations, expired domains, or domains with no DNS records.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block unresolved domains
if (classification.is_unresolved) {
  throw new Error('Email domain could not be verified. Please use a different address.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block unresolved domains
if classification.get('is_unresolved'):
    raise ValueError('Email domain could not be verified. Please use a different address.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block unresolved domains
if ($classification['is_unresolved'] ?? false) {
    throw new Exception('Email domain could not be verified. Please use a different address.');
}

7. Block Public Email Providers

Use this check to reject free public email providers such as Gmail, Yahoo, and Outlook. Useful for B2B sign-up forms that require a company email address.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block public email providers
if (classification.is_public) {
  throw new Error('Please use your company email address.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block public email providers
if classification.get('is_public'):
    raise ValueError('Please use your company email address.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block public email providers
if ($classification['is_public'] ?? false) {
    throw new Exception('Please use your company email address.');
}

8. Block Role-Based Emails

Use this check to reject role-based addresses such as admin@, support@, info@, and noreply@ that are shared across teams and not tied to an individual user.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block role-based emails
if (classification.is_role_based) {
  throw new Error('Role-based email addresses are not allowed. Please use a personal email.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block role-based emails
if classification.get('is_role_based'):
    raise ValueError('Role-based email addresses are not allowed. Please use a personal email.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block role-based emails
if ($classification['is_role_based'] ?? false) {
    throw new Exception('Role-based email addresses are not allowed. Please use a personal email.');
}

9. Block Alias Emails

Use this check to reject email aliases — addresses containing a + suffix (e.g. [email protected]) that could be used to bypass uniqueness checks or track your signup form.

const result = await client.verification.checkEmail(email);
const { classification } = result.data;

// Block alias emails
if (classification.is_alias) {
  throw new Error('Email aliases are not allowed. Please use your primary email address.');
}

import requests

response = requests.get(
    f'https://api.stopreg.com/api/v1/verify/email/{email}',
    headers={'x-api-token': api_token}
)
classification = response.json()['data']['classification']

# Block alias emails
if classification.get('is_alias'):
    raise ValueError('Email aliases are not allowed. Please use your primary email address.')

<?php
$ch = curl_init('https://api.stopreg.com/api/v1/verify/email/' . urlencode($email));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['x-api-token: ' . $apiToken]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$classification = $body['data']['classification'] ?? [];

// Block alias emails
if ($classification['is_alias'] ?? false) {
    throw new Exception('Email aliases are not allowed. Please use your primary email address.');
}

Allowing Trusted Domains

To allow specific domain names regardless of their classification, add them to the Allow List from the Manage Domains page.

Domains added to the allow list will bypass validation restrictions and Form Abuse Shield checks entirely. This is useful for internal tools, partner organisations, or known corporate domains that may be flagged by classification rules.

Example trusted domains:

example.com
company.org
business.net

Form Abuse Shield

To prevent abuse from unresolved or suspicious custom domains, configure Form Abuse Shield from the Manage Domains page.

The Abuse Shield system works based on your selected validation configuration and detection rules.
The system monitors unresolved custom domains and automatically performs the configured action — block or notify — once the detection threshold is reached.
Domains added to the allow list are excluded from Abuse Shield monitoring.

Support

If you need additional help or have questions, contact our support team at [email protected] or visit your dashboard for more resources.

Verify Your Email

Product Documentation

Here is an overview of what stopreg is all about

Getting Started with StopReg

What is StopReg?

Key Features

Quick Start

API Authentication

Getting Your API Token

Using Your API Token

Security Best Practices

Rate Limits

API Endpoints

Email Verification

Domain Verification

Path Parameters

Request Examples

Response Format

Response Fields

Top-Level Fields

Domain & Registry Analytics (data.domain)

Input Intelligence (data.input)

Infrastructure Analytics (data.mail_server)

Strategic Classification (data.classification)

Custom Policy Logic (data.policy)

Error Responses

HTTP Status Codes

Official Libraries

Node.js SDK (NPM)

Laravel SDK (Composer)

Code Examples

JavaScript (Node.js)

Python

PHP

cURL

Integration in Registration Forms

Best Practices & Troubleshooting

Best Practices

Common Use Cases

Troubleshooting

API Returns Error

Slow Response Times

False Positives

Recommended Validation Configurations

1. Block Disposable Email Domains Only

2. Allow Public & Custom Domains

3. Allow Business Domains Only

4. Allow Public Email Providers Only

5. Block Relay Emails

6. Block Unresolved Domains

7. Block Public Email Providers

8. Block Role-Based Emails

9. Block Alias Emails

Allowing Trusted Domains

Form Abuse Shield

Support