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
• 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:

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 POST request with your API token in the header and the email address in the body. 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:

POST https://api.stopreg.com/api/v1/verify/email

Copy

Domain Verification

Endpoint:

POST https://api.stopreg.com/api/v1/verify/domain

Copy

Body Parameters (JSON)

• 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 Example

POST https://api.stopreg.com/api/v1/verify/email

Headers:
  x-api-token: YOUR_API_TOKEN
  Content-Type: application/json

Body:
  { "email": "test@example.com" }

Copy

Response Format

The API returns a JSON response with the following structure:

{
  "status": 200,
  "message": "success",
  "description": "Check successful",
  "input": {
    "email": "user@example.com",
    "normalized": "user@example.com",
    "suggestion": null
  },
  "domain": {
    "name": "example.com",
    "provider": "Google"
  },
  "mail_server": {
    "mx_found": true,
    "mx_records": ["aspmx.l.google.com"]
  },
  "classification": {
    "is_disposable": false,
    "is_role_based": false,
    "is_relay": false,
    "is_alias": false,
    "is_unresolved": false,
    "is_public": true
  },
  "policy": {
    "blocklisted": false,
    "allowlisted": false
  },
  "data": { /* copy of above results */ }
}

Copy

Response Fields

• status: HTTP status code of the response
• message: Status text ("success" or "error")
• description: Human-readable description of the result
• input: Contains raw input, normalized value, and typo suggestions
• domain: Details about the domain and its identified provider
• mail_server: MX record status and resolved hosts
• classification: Boolean flags for disposable, relay, public, role-based, alias, and unresolved status
• policy: User-specific blocklist and allowlist status

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.",
  "error": "invalid_token",
  "data": null
}

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

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 = 'test@disposable.com';

const response = await fetch('https://api.stopreg.com/api/v1/verify/email', {
    method: 'POST',
    headers: {
      'x-api-token': apiToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email }),
  }
);

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

if (data.classification?.is_disposable) {
  console.log('Domain is blocked');
}

Copy

Python

import requests

api_token = 'YOUR_API_TOKEN'
email = 'test@disposable.com'

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

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

data = response.json()
print(data)

Copy

PHP

<?php

$apiToken = 'YOUR_API_TOKEN';
$email = 'test@disposable.com';

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

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['email' => $email]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-token: ' . $apiToken,
    'Content-Type: application/json'
]);

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

curl_close($ch);

if ($data['classification']['is_disposable']) {
    echo 'Domain is blocked';
}
?>

Copy

cURL

curl -X POST \
  "https://api.stopreg.com/api/v1/verify/email" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@disposable.com"}'

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 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
• Check your rate limit status in the dashboard

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

Support

If you need additional help or have questions, contact our support team at support@stopreg.com or visit your dashboard for more resources.