API Documentation

Getting Started

CheckSignup provides a simple REST API to validate email addresses. The API checks for:

Valid email syntax
MX record existence
Disposable/temporary email domains
Email forwarding services
Free email providers
Role-based addresses (info@, support@, etc.)
Typos in common domains

Authentication

All API requests require an API key. Get yours at app.checksignup.com.

Query Parameter

GET /validate?email=user@example.com&key=YOUR_API_KEY

Header

X-API-Key: YOUR_API_KEY

Validate Endpoint

GET https://api.checksignup.com/validate

Parameters

Name	Type	Required	Description
`email`	string	Yes	Email address to validate
`key`	string	Yes*	Your API key (*or use header)
`ip`	string	No	End-user IP for VPN/proxy/hosting detection

Response Format

{
  "email": "john.doe+test@gmail.com",
  "normalized": "johndoe@gmail.com",
  "domain": "gmail.com",
  "mx": ["gmail-smtp-in.l.google.com"],
  "valid": {
    "syntax": true,
    "mx": true
  },
  "flags": {
    "disposable": false,
    "forwarding": false,
    "free": true,
    "catchall": false,
    "role": false
  },
  "typo_suggestion": null
}

Fields

Field	Type	Description
`email`	string	Original email submitted
`normalized`	string	Canonical form (Gmail dots/plus removed)
`domain`	string	Email domain
`mx`	array	MX record hostnames (max 3)
`valid`	object	Validation results (syntax, mx)
`flags`	object	Detection flags (see below)
`typo_suggestion`	string\|null	Suggested correction if typo detected

Flags Explained

Flag	true means
`disposable`	Temporary/throwaway email (Mailinator, etc.)
`forwarding`	Email forwarding service (SimpleLogin, Firefox Relay)
`free`	Free email provider (Gmail, Yahoo, Outlook)
`catchall`	Domain accepts any address
`role`	Generic role address (info@, support@, admin@)

Code Examples

cURL

# Basic validation
curl "https://api.checksignup.com/validate?email=test@gmail.com&key=YOUR_API_KEY"

# With IP for VPN/proxy detection
curl "https://api.checksignup.com/validate?email=test@gmail.com&key=YOUR_API_KEY&ip=1.2.3.4"

Python

import requests

# Get end-user IP from your request (e.g., Flask/Django)
user_ip = request.headers.get('X-Forwarded-For', request.remote_addr)

response = requests.get(
    "https://api.checksignup.com/validate",
    params={
        "email": "test@gmail.com",
        "key": "YOUR_API_KEY",
        "ip": user_ip  # Pass end-user IP for VPN/proxy detection
    }
)
data = response.json()

if data["flags"]["disposable"]:
    print("Blocked: disposable email")
elif not data["valid"]["mx"]:
    print("Blocked: invalid domain")

JavaScript (Node.js)

// Get end-user IP from your request (e.g., Express)
const userIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;

const params = new URLSearchParams({
  email: 'test@gmail.com',
  key: 'YOUR_API_KEY',
  ip: userIp  // Pass end-user IP for VPN/proxy detection
});

const response = await fetch(
  `https://api.checksignup.com/validate?${params}`
);
const data = await response.json();

if (data.flags.disposable) {
  throw new Error("Please use a permanent email address");
}