Product Documentation

Getting Started with StopReg

Email Intelligence for Signup, Fraud, and Abuse Prevention

StopReg is an email intelligence API designed to help applications identify disposable, temporary, relay, alias, role-based, public email, edu, isp and private email addresses before they enter your system.

Use StopReg to evaluate email addresses and domains in real time, enforce your signup policies, and reduce unwanted registrations, trial abuse, and low-quality user data.

The API returns structured classification and mail infrastructure data, allowing you to decide exactly how your application should handle each address.

What You Can Detect

StopReg goes beyond basic email syntax validation. Depending on the address and domain, the API can identify:

• Disposable and temporary emails used for short-lived registrations
• Relay addresses that forward messages through another service
• Email aliases and sub-addressing patterns
• Role-based addresses such as admin@ and support@
• Public email providers such as Gmail, Outlook, and Yahoo
• ISP email addresses associated with internet service providers
• Educational (EDU) email addresses associated with educational institutions
• Private and custom domains
• Mail server and MX information
• Email provider and infrastructure information
• Domain and email classification signals
• Policy-based allow, warn, or block decisions

Built for Real-Time Validation

StopReg is designed for applications that need to make an email decision during a signup, checkout, free-trial registration, newsletter subscription, or other form submission.

A simple API request returns structured JSON that your application can use to determine whether an address should be accepted, flagged, or blocked.

Flexible Enforcement

StopReg does not force you to use a single blocking rule. You can build your own flexible enforcement policy around the classification data returned by the API.

For example, you can block disposable addresses while continuing to accept relay, private, public, ISP, EDU, and role-based addresses. You can also combine multiple signals when your application requires stricter validation, such as blocking disposable, relay, and alias addresses while requiring the domain to have valid MX records.

This allows you to define validation rules based on your application's specific requirements rather than applying the same policy to every email address.

Simple Integration

StopReg uses a REST API over HTTPS and supports API-token authentication. You can integrate it into virtually any backend or application stack using standard HTTP requests.

Official libraries and examples are available for popular development environments, including Node.js and Laravel, with additional examples for JavaScript, Python, PHP, and cURL.

Get Started

Start validating email addresses with StopReg in just a few steps:

1. Create your account: Sign up for a StopReg account and access your API dashboard.
2. Get your API token: Generate an API token from your dashboard and keep it securely stored on your server.
3. Choose an API endpoint: Use the Email Validation API to analyze individual email addresses or the Domain Validation API when you only need to evaluate a domain.
4. Send your request: Include your API token and the email address or domain you want to validate. StopReg returns a structured JSON response containing the available classification and validation signals.
5. Apply your enforcement policy: Use the returned results to determine whether to allow, warn, or block an address based on your application's requirements.

Example Use Case

For a signup form, you can validate an email address before creating the account. Your application can then use StopReg's response to identify disposable, temporary, relay, alias, role-based, ISP, EDU, public, or other email classifications and apply your own validation rules.

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
• Free, ISP & EDU Detection: Identify free, ISP, and educational email providers for better email classification
• Domain Abuse Shield: Automatically detect custom or relay domains used for repeated or abusive submissions
• Enforcement Policies: Choose whether to allow, warn, or block domains based on their classification

The sections below cover authentication, endpoints, response fields, SDKs, code examples, validation configurations, best practices, and troubleshooting.

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 are limited to 20 requests per minute, while paid plans allow up to 5 requests per second.

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 (shown here for authenticated requests):

{
  "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_private": false,
      "is_public": true,
      "is_role_based": false,
      "is_alias": false
    },
    "list_match": {
      "blocklisted": false,
      "block_source": null,
      "allowlisted": false
    },
    "policy": {
      "action": "allow",
      "reason_code": "UNKNOWN",
      "reason": "Email classification is pending determination.",
      "risk": "low"
    }
  }
}

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)

Enforcement & Policy (data.policy)

List Match (data.list_match)

Note: The policy object is only fully populated for authenticated requests (with a valid x-api-token header). Anonymous requests receive a simplified response with a default message.

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 policy = response.data.policy;

  if (policy?.action === 'block') {
    console.log('Email blocked:', policy.reason);
  } else if (policy?.action === 'warn') {
    console.log('Email flagged:', policy.reason);
  } else {
    console.log('Email allowed');
  }
} 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');

  // Check policy decision from enforcement rules
  const policy = response.data.policy;

  if (policy?.action === 'block') {
    console.log('Domain blocked:', policy.reason);
  } else if (policy?.action === 'warn') {
    console.log('Domain flagged:', policy.reason);
  } else {
    console.log('Domain allowed');
  }
} 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]');

    // Check policy decision from enforcement rules
    $policy = $result['data']['policy'] ?? null;

    if ($policy && $policy['action'] === 'block') {
        return back()->withErrors(['email' => $policy['reason'] ?? 'This email is not allowed.']);
    } elseif ($policy && $policy['action'] === 'warn') {
        session()->flash('warning', $policy['reason'] ?? 'This email is flagged.');
    }
} catch (StopRegException $e) {
    // Handle error
}

Copy

Domain Verification:

use StopReg\Laravel\Facades\StopReg;

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

    // Check policy decision from enforcement rules
    $policy = $result['data']['policy'] ?? null;

    if ($policy && $policy['action'] === 'block') {
        return back()->withErrors(['domain' => $policy['reason'] ?? 'This domain is not allowed.']);
    } elseif ($policy && $policy['action'] === 'warn') {
        session()->flash('warning', $policy['reason'] ?? 'This domain is flagged.');
    }
} 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.
• 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

Domain Management

Form Abuse Shield is a premium feature that automatically detects suspicious activity from private and relay email domains and helps prevent repeated registrations from abusive domains. 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 registration activity from private and relay domains. When a domain reaches your configured registration threshold within the selected time window, StopReg can automatically notify you or block further registrations from that domain. When the threshold is reached, the system can:

• Notify Mode: Automatically send you an email alert with the domain details and threshold information.
• Block Mode: Automatically block the domain from making further registrations.

Key Features

• Automatic Detection: Monitors multiple registrations from the same private or relay domain.
• Configurable Threshold: Set the number of requests from a private or relay domain before an action is triggered, from 2 to 50 requests.
• Flexible Time Window: Choose a monitoring period of 1, 3, or 7 days.
• Two Action Modes: Choose Notify for email alerts or Block for automatic blocking.
• Dashboard Control: Manage, review, and adjust your Form Abuse Shield settings at any time.

How Form Abuse Shield Works

Step 1: Enable and Configure

Navigate to Manage Domains and configure your Form Abuse Shield settings.

• Detection Rule: Set the registration threshold, such as blocking after 5 requests.
• Time Window: Choose your monitoring period: 1, 3, or 7 days.
• Action: Select Notify for alerts or Block for automatic blocking.
• Take No Action: The system will not monitor or take action on domain registrations, regardless of the configured threshold.

Step 2: Monitoring Begins

Once configured, Form Abuse Shield continuously monitors incoming registration activity.

• Automatic Counting: Counts requests from private or relay domains for each domain within your specified time window.
• Tracks Registration Activity: Monitors the number of registrations associated with each domain.
• Compares Against Threshold: Compares registration activity with your configured threshold.

Step 3: Automatic Action Is Triggered

When a domain reaches your configured threshold:

• Notify Mode: Sends you an email alert containing the domain details and threshold information.
• Block Mode: Automatically adds the domain to your blocklist and rejects further registrations from that domain.

Notify Mode vs. Block Mode

Manual Allowlist Protection

Critical Protection: Domains that you manually add to your allowlist are protected from automatic blocking by Form Abuse Shield, regardless of:

• How many requests the domain receives
• Whether you switch from Notify to Block mode
• How high or low your threshold is configured

This ensures that manually allowlisted domains remain trusted and are never automatically blocked by Form Abuse Shield.

Manual Blocklist Protection

Similarly, domains that you manually add to your blocklist remain blocked and cannot be unblocked by Form Abuse Shield's automatic processes.

Configuration Examples

Balanced Setup

• Threshold: 5 requests
• Time Window: 3 days
• Action: Notify
• Result: Helps identify suspicious registration activity while allowing you to review domains before blocking them.

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 in Notify mode will be auto-blocked if they continue to receive 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 on the Scale plan and above.

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.