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 straightforward. You'll use a GET request with your API token and the email address you want to validate. 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 your account settings or API section
3. Copy your API token (you can regenerate it at any time if needed)

Using Your API Token

Your API token is included directly in the API endpoint URL. The format is:

https://api.stopreg.com/api/v1/check/YOUR_API_TOKEN?email=user@example.com

Replace YOUR_API_TOKEN with your actual API token from the dashboard.

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 Validation Endpoint

Endpoint:

GET https://api.stopreg.com/api/v1/check/{apiToken}?email={email}

Parameters

• apiToken (path parameter, required): Your StopReg API token
• email (query parameter, required): The email address to validate

Request Example

GET https://api.stopreg.com/api/v1/check/YOUR_API_TOKEN?email=test@example.com
Headers:
  Content-Type: application/json

Response Format

The API returns a JSON response with the following structure:

{
  "message": "success",
  "data": {
    "isDisposable": false,
  }
}

Response Fields

• message: Status of the request ("success" or "error")
• data.email: The email address that was checked
• data.isDisposable: Boolean indicating if the email is from a disposable provider
• data.domain: The domain part of the email address

Error Responses

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

{
  "message": "error",
  "description": "Error description here"
}

HTTP Status Codes

• 200 OK: Request successful
• 400 Bad Request: Invalid parameters (missing email or API token)
• 401 Unauthorized: Invalid or missing API token
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: 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@example.com';

const response = await fetch(
  `https://api.stopreg.com/api/v1/check/${apiToken}?email=${encodeURIComponent(email)}`,
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  }
);

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

if (data.data?.isDisposable) {
  console.log('Email is disposable - block registration');
} else {
  console.log('Email is valid - allow registration');
}

Python

import requests

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

url = f'https://api.stopreg.com/api/v1/check/{api_token}?email={email}'

response = requests.get(url, headers={
    'Content-Type': 'application/json'
})

data = response.json()
print(data)

if data.get('data', {}).get('isDisposable'):
    print('Email is disposable - block registration')
else:
    print('Email is valid - allow registration')

PHP

<?php

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

$url = "https://api.stopreg.com/api/v1/check/{$apiToken}?email=" . urlencode($email);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

curl_close($ch);

if ($data['data']['isDisposable']) {
    echo 'Email is disposable - block registration';
} else {
    echo 'Email is valid - allow registration';
}
?>

cURL

curl -X GET \
  "https://api.stopreg.com/api/v1/check/YOUR_API_TOKEN?email=test@example.com" \
  -H "Content-Type: application/json"

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 isDisposable 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.