API Reference

Complete documentation of all Mailsniper API endpoints, parameters, and response formats.

Authentication & Basics

Base URL

https://api.mailsniperapp.com

Authentication

All API requests must include your API key in the Authorization header using Bearer token format.

Authorization: Bearer
                            YOUR_API_KEY_HERE

API Key Security

Keep your API key secret and never expose it in client-side code. Sign up to get your API key.

Rate Limiting

Credit-Based System

Each API call consumes 1 credit from your account balance. Monitor your usage through the dashboard.

Response Headers

X-RateLimit-Remaining Credits left in your account

X-RateLimit-Used Total credits consumed

X-RateLimit-Reset When your rate limit resets (if applicable)

429 Too Many Requests

When you receive a 429 response, check the X-RateLimit-* headers to understand your current usage. Implement exponential backoff and retry logic in your applications.

CORE

Email Verification

GET /v1/verify/email/{email}

Validates an email address and returns comprehensive information about the domain quality, including whether it's disposable, spam-related, or suspicious.

Parameters

Parameter	Type	Required	Description
email	string	Required	The email address to validate

Example Request

curl -X GET \
  "https://api.mailsniperapp.com/v1/verify/email/[email protected]" \
  -H "Authorization: Bearer <API-KEY-HERE>"

Run this in your terminal (Linux/Mac) or command prompt (Windows with curl installed).

const response = await fetch(
  'https://api.mailsniperapp.com/v1/verify/email/[email protected]',
  {
    headers: {
      'Authorization': 'Bearer <API-KEY-HERE>'
    }
  }
);

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

Save as test.js and run with node test.js (requires Node.js).

import requests

response = requests.get(
    'https://api.mailsniperapp.com/v1/verify/email/[email protected]',
    headers={
        'Authorization': 'Bearer <API-KEY-HERE>'
    }
)

print(response.json())

Save as test.py and run with python test.py (requires requests: pip install requests).

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
    'https://api.mailsniperapp.com/v1/verify/email/[email protected]');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <API-KEY-HERE>'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Save as test.php and run with php test.php.

Replace your API key

Make sure to replace <API-KEY-HERE> with your full API key from the dashboard.

Response Schema & Field Guide

Sample Response

Here's a complete response showing all available fields:

{
  "email": "[email protected]",
  "user": "user",
  "domain": "10minutemail.com",
  "is_valid": true,
  "is_disposable": true,
  "is_public_provider": false,
  "is_university": false,
  "is_spam": true,
  "risk": 85,
  "dns": {
    "mx_servers": ["mx1.10minutemail.com", "mx2.10minutemail.com"],
    "has_a_root_record": true
  }
}

Basic Fields

`email` string

The original email address that was validated (normalized to lowercase).

`user` string

The local part of the email address (everything before the @ symbol).

`domain` string

The domain part of the email address (everything after the @ symbol).

Validation Flags

Boolean fields that provide specific information about the domain characteristics.

`is_valid` boolean

Indicates if the email has a valid format and the domain exists with proper DNS records.

Usage:

Use this for basic email format validation. If false, the email is definitely invalid and should be rejected.

`is_disposable` boolean

True if the domain is a temporary or disposable email service (like 10minutemail, guerrillamail, etc.).

`is_spam` boolean

True if the domain is known for spam, abuse, or other malicious activities. Sources include spam domain lists, abuse reports, and reputation databases.

`is_public_provider` boolean

True if the domain is a free email provider like Gmail, Yahoo, Outlook, etc.

`is_university` boolean

True if the domain belongs to a university or college.

Risk Assessment

`risk` integer

Risk score from 0-100 combining multiple factors. Use this for decision-making when you need a precise numeric metric (0 = lowest risk, 100 = highest risk).

✅

0-30

Low risk. Domain appears safe and legitimate. Good for business use.

⚠️

31-70

Medium risk. Some concerning factors. May require additional verification.

🚫

71-100

High risk. Multiple red flags. Consider blocking or manual review.

DNS Information

`dns` object

Technical DNS information about the domain's mail configuration.

`mx_servers` array

List of mail server hostnames that handle email for this domain.

["mx1.example.com",
                                            "mx2.example.com"]

`has_a_root_record` boolean

Indicates if the domain has an A record (basic website/domain existence check).

Decision Logic Examples

Here are some common validation logic patterns based on the response fields:

🛡️ Strict Validation (High Security)

Block if:

• is_disposable is true
• is_spam is true
• risk >= 71
• is_valid is false

Use case: Financial services, B2B platforms, premium products

⚖️ Moderate Validation (Balanced)

Block if:

• is_disposable is true
• is_spam is true

Flag for review if:

• risk >= 71

Use case: Most SaaS applications, e-commerce, general business use

🚪 Permissive Validation (Low Friction)

Block only if:

• is_valid is false
• is_spam is true

Use case: Content platforms, social networks, consumer apps where maximizing signups is important

UTILITY

Usage Information

GET /v1/usage

Get information about your current API usage, including remaining credits and quota limits.

Example Request

curl -X GET \
  "https://api.mailsniperapp.com/v1/usage/[email protected]" \
  -H "Authorization: Bearer <API-KEY-HERE>"

Run this in your terminal (Linux/Mac) or command prompt (Windows with curl installed).

const response = await fetch(
  'https://api.mailsniperapp.com/v1/usage/[email protected]',
  {
    headers: {
      'Authorization': 'Bearer <API-KEY-HERE>'
    }
  }
);

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

Save as test.js and run with node test.js (requires Node.js).

import requests

response = requests.get(
    'https://api.mailsniperapp.com/v1/usage/[email protected]',
    headers={
        'Authorization': 'Bearer <API-KEY-HERE>'
    }
)

print(response.json())

Save as test.py and run with python test.py (requires requests: pip install requests).

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
    'https://api.mailsniperapp.com/v1/usage/[email protected]');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <API-KEY-HERE>'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Save as test.php and run with php test.php.

Replace your API key

Make sure to replace <API-KEY-HERE> with your full API key from the dashboard.

Response Schema

{
  "total": 10000,                   // Total credits allocated
  "used": 1250,                     // Credits consumed
  "remaining": 8750,                // Credits remaining
  "percentage_used": 12.5,          // Percentage of quota used
  "is_approaching_limit": false     // Whether you're close to limit
}

Error Responses

When an error occurs, the API returns an appropriate HTTP status code along with a JSON error response.

400 Bad Request

Invalid email format or missing required parameters

{
  "error_code": "invalid_email_format",
  "message": "Invalid email format: invalid-email"
}

401 Unauthorized

Missing or invalid API key

{
  "error_code": "authentication_required",
  "message": "Authentication required. Please provide a valid API key in the Authorization header as 'Bearer YOUR_API_KEY'."
}

429 Too Many Requests

Rate limit exceeded or insufficient credits

{
  "error_code": "quota_exceeded",
  "message": "Request quota exceeded. Please upgrade your plan or purchase additional requests to continue."
}

Response Headers:

• X-RateLimit-Remaining: 0 - No credits left
• Retry-After: 3600 - Seconds until you can retry

Need more help?

Our API documentation provides comprehensive information for integrating email validation into your applications. If you have any further questions or need additional support, please get in touch with our team.

Contact Support

API Reference

Authentication & Basics

Base URL

Authentication

API Key Security

Rate Limiting

Credit-Based System

Response Headers

429 Too Many Requests

Email Verification

Parameters

Example Request

Replace your API key

Response Schema & Field Guide

Sample Response

Basic Fields

email string

user string

domain string

Validation Flags

is_valid boolean

Usage:

is_disposable boolean

is_spam boolean

is_public_provider boolean

is_university boolean

Risk Assessment

risk integer

0-30

31-70

71-100

DNS Information

dns object

mx_servers array

has_a_root_record boolean

Decision Logic Examples

🛡️ Strict Validation (High Security)

⚖️ Moderate Validation (Balanced)

🚪 Permissive Validation (Low Friction)

Usage Information

Example Request

Replace your API key

Response Schema

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

Need more help?

`email` string

`user` string

`domain` string

`is_valid` boolean

`is_disposable` boolean

`is_spam` boolean

`is_public_provider` boolean

`is_university` boolean

`risk` integer

`dns` object

`mx_servers` array

`has_a_root_record` boolean