Product 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
• Extensive DEA Coverage: Detect disposable emails using our large and constantly growing domain 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
• Blacklisting Support: Blacklist unwanted domains to prevent fake signups and low-quality registrations.
• Role, Alias & Relay Detection: Identify role-based, alias, and relay email addresses for cleaner user data.

Quick Start

To get started with StopReg, you'll need:

1. Create an account at stopreg.com
2. Get your API token from your dashboard
3. 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

1. Log in to your StopReg dashboard
2. Navigate to the API section or locate the API token on your Dashboard home
3. 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

Copy

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}

Copy

Domain Verification

Endpoint:

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

Copy

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

Copy

Domain Verification

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

Headers:
  x-api-token: YOUR_API_TOKEN

Copy

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,
      "email_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"
    }
  }
}

Copy

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

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

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"
  }
}

Copy

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

Copy

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);
}

Copy

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);
}

Copy

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

Copy

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
}

Copy

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
}

Copy

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');
}

Copy

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')

Copy

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';
}
?>

Copy

cURL

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

Copy

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            ✓

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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.');
}

Copy

JavaScript Python PHP

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

Copy

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.

Form Abuse Shield

Form Abuse Shield is a premium feature that automatically detects and blocks suspicious email domains from registering on your platform. It works alongside email validation to provide an additional layer of protection against form abuse, spam registrations, and fraudulent activity.

What is Form Abuse Shield?

Form Abuse Shield monitors unresolved and suspicious domains that reach your configured threshold. When a domain exceeds the threshold, the system automatically:

• Notify mode: Automatically adds the domain to your allowlist and sends you an alert
• Block mode: Automatically blocks the domain from further registrations

Key Features

• Automatic Detection: Monitors unresolved domains and suspicious registration patterns
• Configurable Threshold: Set the number of unresolved requests before action is triggered (2-50 requests)
• Flexible Time Window: Choose your monitoring period (1, 3, or 7 days)
• Two Action Modes: Notify (alert + allowlist) or Block (automatic blocking)
• Manual Override Protection: Manually allowlisted domains are never auto-blocked, permanently protected
• Dashboard Control: Manage, review, and adjust abuse shield settings anytime

How Form Abuse Shield Works

Step 1: Enable and Configure

Navigate to Manage Domains and configure your abuse shield settings:

• Detection Rule: Set the threshold (e.g., block after 5 unresolved requests)
• Time Window: Choose your lookback period (1, 3, or 7 days)
• Action: Select Notify (alert only) or Block (automatic blocking)

Step 2: Monitoring Begins

Once configured, Form Abuse Shield continuously monitors incoming domain registrations:

• Counts unresolved requests for each domain within your specified time window
• Tracks suspicious patterns and registration velocity
• Compares metrics against your configured threshold

Step 3: Automatic Action Triggered

When a domain reaches your threshold:

• Notify Mode: Domain is automatically added to your allowlist and you receive an email alert with domain details and threshold information
• Block Mode: Domain is automatically added to your blocklist and further registrations from that domain are rejected

Notify Mode vs. Block Mode

Manual Allowlist Protection

Critical Protection: Domains that you manually allowlist are permanently protected and will never be automatically blocked by Form Abuse Shield, regardless of:

• How many unresolved requests they receive
• Whether you switch from Notify to Block mode
• How high your threshold is configured

This ensures that manually allowlisted domains remain permanently trusted and are never blocked by any request made through your account.

Manual Blocklist Protection

Similarly, domains that you manually block will remain blocked permanently and cannot be unblocked by any automatic process.

Configuration Examples

Balanced Setup (Recommended)

• Threshold: 5 unresolved requests
• Window: 3 days
• Action: Notify
• Result: Good balance between security and false positive reduction

FAQ

Q: Can I manually allowlist a domain to prevent auto-blocking?

A: Yes! Manually allowlisted domains are permanently protected and will never be auto-blocked, regardless of Form Abuse Shield settings.

Q: What happens if I switch from Notify to Block mode?

A: Domains previously auto-added to the allowlist in Notify mode may be auto-blocked if they continue to receive unresolved requests and reach your threshold. However, manually allowlisted domains will remain protected.

Q: Can I unblock an automatically blocked domain?

A: Yes, you can manually remove it from your blocklist at any time from the dashboard.

Q: Is Form Abuse Shield available on all plans?

A: Form Abuse Shield is a premium feature available to paid plan subscribers. Free accounts do not have access to automatic abuse detection.

Support

If you have questions about Form Abuse Shield or need help configuring it, contact our support team at [email protected] or visit the Manage Domains page to get started.