BLACK FRIDAY DEAL!
Get $100 OFF on lifetime access!

Check Endpoint

The primary API endpoint for checking if an email address or domain is disposable.

GET /api/v1/check

Check if an email address or domain is disposable

Request

Query Parameters

ParameterTypeRequiredDescription
qstringYesEmail address or domain to check

Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYYes

Examples

Check an Email Address

Request 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://puresignup.com/api/v1/check?q=user@guerrillamail.com"
Response - High Risk 
{
  "success": true,
  "data": {
    "subject": "user@guerrillamail.com",
    "subject_type": "email",
    "risk_level": "high",
    "domain": "guerrillamail.com",
    "sources": ["SRC_A", "SRC_B", "SRC_C", "SRC_D", "SRC_F"],
    "last_updated": "2025-11-17T18:29:54.827Z",
    "checked_at": "2025-11-17T18:30:00.000Z"
  }
}

Check a Domain Directly

Request 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://puresignup.com/api/v1/check?q=gmail.com"
Response - Low Risk 
{
  "success": true,
  "data": {
    "subject": "gmail.com",
    "subject_type": "domain",
    "risk_level": "low",
    "domain": "gmail.com",
    "checked_at": "2025-11-17T18:30:00.000Z"
  }
}

Response Fields

FieldTypeAlways PresentDescription
successbooleanYesIndicates if the request was successful
data.subjectstringYesThe email or domain that was checked
data.subject_typestringYesEither "email" or "domain"
data.risk_levelstringYes"high" if disposable, "low" if legitimate, "unknown" for IPs
data.domainstringYesThe domain extracted from the email (or the domain itself)
data.sourcesstring[]Only if high riskList of sources that identified this domain as disposable
data.last_updatedstringOnly if high riskISO 8601 timestamp of when this domain was last updated in our database
data.checked_atstringYesISO 8601 timestamp of when this check was performed

Input Types

Email Addresses

Pass a full email address to check if the domain portion is disposable:

https://puresignup.com/api/v1/check?q=user@example.com

Domains

Check a domain directly without an email address:

https://puresignup.com/api/v1/check?q=example.com

IP Addresses (Coming Soon)

IP address checking is planned but not yet implemented:

Current IP Response 
{
  "success": true,
  "data": {
    "subject": "192.168.1.1",
    "subject_type": "ip",
    "risk_level": "unknown",
    "message": "IP address checking is not yet implemented"
  }
}

Understanding Risk Levels

High Risk

Domain is confirmed disposable by one or more authoritative sources. Block or flag this signup.

Low Risk

Domain is not in our disposable database. Likely a legitimate email provider. Allow this signup.

Unknown (IP addresses only)

IP address checking is not yet supported. Feature coming soon.

Error Responses

Missing Query Parameter

400 Bad Request 
{
  "success": false,
  "error": "Missing required parameter: 'q'"
}

Invalid Email Format

400 Bad Request 
{
  "success": false,
  "error": "Invalid email format"
}

Invalid Domain Format

400 Bad Request 
{
  "success": false,
  "error": "Invalid domain format. Domain must include a TLD (e.g., example.com)",
  "domain": "invalid-domain"
}

Authentication Failed

401 Unauthorized 
{
  "success": false,
  "error": "Invalid or missing API key"
}

Internal Server Error

500 Internal Server Error 
{
  "success": false,
  "error": "Internal server error"
}

For more details on error handling, see the Error Codes reference.

Rate Limiting

Rate limits vary by plan. See pricing page for details. When rate limited, you'll receive a 429 error:

429 Too Many Requests 
{
  "success": false,
  "error": "Rate limit exceeded"
}

Code Examples

JavaScript / TypeScript

async function checkEmail(email: string): Promise<boolean> {
  try {
    const response = await fetch(
      'https://puresignup.com/api/v1/check?q=' + encodeURIComponent(email),
      {
        headers: {
          'Authorization': 'Bearer ' + process.env.PureSignup_API_KEY
        }
      }
    );

    if (!response.ok) {
      console.error('API error:', response.status);
      return false; // Fail open on API errors
    }

    const data = await response.json();
    return data.success && data.data.risk_level === 'high';
  } catch (error) {
    console.error('Failed to check email:', error);
    return false; // Fail open on network errors
  }
}

Python

import os
import requests
from typing import bool

def check_email(email: str) -> bool:
    """Check if an email is disposable. Returns True if disposable."""
    try:
        response = requests.get(
            'https://puresignup.com/api/v1/check',
            params={'q': email},
            headers={
                'Authorization': f'Bearer {os.environ.get("PureSignup_API_KEY")}'
            },
            timeout=5
        )
        
        if not response.ok:
            print(f'API error: {response.status_code}')
            return False  # Fail open on API errors
        
        data = response.json()
        return data.get('success') and data.get('data', {}).get('risk_level') == 'high'
    except Exception as e:
        print(f'Failed to check email: {e}')
        return False  # Fail open on errors

Best Practices

  • Always check server-side: Never rely solely on client-side validation
  • Fail open: If the API is unavailable, allow the signup to proceed
  • Cache results: Cache domain lookups for a few hours to reduce API calls
  • URL encode parameters: Always URL-encode the q parameter
  • Handle timeouts: Set reasonable request timeouts (5-10 seconds)
  • Log rejections: Keep track of blocked signups for analysis

Next Steps

© 2025 PureSignup. All rights reserved.