Mailbloc Documentation
Mailbloc is a lightweight email and IP validation API that provides instant protection against fake sign-ups, disposable emails, and fraudulent registrations. With a single API call, you can validate email addresses and IP addresses to keep your user base clean and secure.
What Mailbloc Does
Email Validation: Detect disposable email addresses, verify MX records, identify privacy forwarding services, and assess email quality.
IP Analysis: Check IP addresses against threat databases for malicious activity, TOR networks, VPNs, and known fraud patterns.
Risk Classification: Get instant risk levels (HIGH, MEDIUM, LOW, NONE) with specific reason codes explaining why.
Simple Integration: Just make an API call with your Bearer token - no complex setup or authentication flows.
Getting Started
Quick Start
Getting started with Mailbloc is remarkably simple. You just need to make API calls to our endpoint with your API token and interpret the risk level in the response.
1. Sign Up
Create your account at mailbloc.com. No password needed! We'll send you a magic link to access your account.
2. Get Your API Token
Once signed up, you'll see your API token on your welcome page. Copy it and keep it secure - you'll use this in the Authorization header.
3. Make API Calls
Start validating emails and IPs immediately by making GET requests to https://api.mailbloc.com/check with your Bearer token.
4. Interpret the Risk Level
The response includes a risk_level field with one of four values:
"high"- Block this signup immediately (disposable email, malicious IP, etc.)"medium"- Moderate risk - we strongly recommend blocking (privacy forwarding, suspicious patterns)"low"- Minimal risk, acceptable quality (free email providers like Gmail)"none"- No risk indicators found (clean corporate email with valid MX)
Best Practice: Always block "high" risk. We strongly recommend blocking "medium" risk as well for maximum protection.
API Reference
API Endpoint
The Mailbloc API has a single endpoint for all validation requests:
GET https://api.mailbloc.com/check
Authentication
Include your API token in the Authorization header:
Authorization: Bearer YOUR_API_TOKEN
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email |
string | No* | Email address to validate (must contain '@') |
ip |
string | No* | IPv4 address to check (e.g., 192.168.1.1) |
* At least one of email or ip must be provided
Example Request
Here's a quick example using curl:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
"https://api.mailbloc.com/[email protected]&ip=1.19.1.18"
Response Format
All successful responses return JSON with this structure:
{
"risk_level": "high",
"reasons": ["disposable_email", "tor_network_ip"]
}
Response Fields
| Field | Type | Description |
|---|---|---|
risk_level |
string | Risk classification: "high", "medium", "low", or "none" |
reasons |
array | Array of reason codes explaining the risk (empty array for "none" risk) |
Example Responses
Clean corporate email (NONE risk):
{"risk_level": "none", "reasons": []}
Free email provider (LOW risk):
{"risk_level": "low", "reasons": ["free_email"]}
Privacy forwarding service (MEDIUM risk):
{"risk_level": "medium", "reasons": ["privacy_email"]}
Disposable email (HIGH risk):
{"risk_level": "high", "reasons": ["disposable_email"]}
TOR network IP (HIGH risk):
{"risk_level": "high", "reasons": ["tor_network_ip"]}
Multiple risk factors:
{"risk_level": "high", "reasons": ["disposable_email", "tor_network_ip"]}
Error Responses
| Status Code | Error | Description |
|---|---|---|
| 400 | missing_params | Neither email nor IP was provided |
| 400 | invalid_email | Email format is incorrect |
| 400 | invalid_ip | IP address format is incorrect |
| 401 | Missing API token | Authorization header is missing |
| 401 | Invalid API token | API token is invalid or expired |
| 429 | Rate limit exceeded | Too many requests in the current time window |
Example Error Response
When validation fails, the API returns a structured error:
{
"error": "invalid_email",
"message": "Email must contain '@' and be properly formatted"
}
JavaScript Example
Use the Fetch API to call Mailbloc from JavaScript:
const apiToken = 'YOUR_API_TOKEN';
const email = '[email protected]';
const ip = '192.168.1.1';
fetch(`https://api.mailbloc.com/check?email=${email}&ip=${ip}`, {
headers: {
'Authorization': `Bearer ${apiToken}`
}
}).then(response => response.json())
.then(data => {
console.log('Risk Level:', data.risk_level);
console.log('Reasons:', data.reasons);
// Block HIGH and MEDIUM risk signups
if (data.risk_level === 'high' || data.risk_level === 'medium') {
alert('Signup blocked: Suspicious activity detected');
} else {
console.log('Signup allowed');
}
})
.catch(error => console.error('Error:', error));
Python Example
Use the requests library to integrate Mailbloc:
import requests
api_token = 'YOUR_API_TOKEN'
email = '[email protected]'
ip = '192.168.1.1'
url = f'https://api.mailbloc.com/check?email={email}&ip={ip}'
headers = {
'Authorization': f'Bearer {api_token}'
}
response = requests.get(url, headers=headers)
data = response.json()
print(f"Risk Level: {data['risk_level']}")
print(f"Reasons: {data['reasons']}")
# Block HIGH and MEDIUM risk signups
if data['risk_level'] in ['high', 'medium']:
print('Signup blocked: Suspicious activity detected')
else:
print('Signup allowed')
PHP Example
Use PHP's cURL extension to call the Mailbloc API:
<?php
$apiToken = 'YOUR_API_TOKEN';
$email = '[email protected]';
$ip = '192.168.1.1';
$url = "https://api.mailbloc.com/check?email=$email&ip=$ip";
$headers = [
'Authorization: Bearer ' . $apiToken
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
echo "Risk Level: " . $data['risk_level'] . "\n";
echo "Reasons: " . implode(', ', $data['reasons']) . "\n";
// Block HIGH and MEDIUM risk signups
if (in_array($data['risk_level'], ['high', 'medium'])) {
echo "Signup blocked: Suspicious activity detected\n";
} else {
echo "Signup allowed\n";
}
?>
Ruby Example
Integrate Mailbloc with Ruby using the Net::HTTP library:
require 'net/http'
require 'json'
api_token = 'YOUR_API_TOKEN'
email = '[email protected]'
ip = '192.168.1.1'
uri = URI("https://api.mailbloc.com/check?email=#{email}&ip=#{ip}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_token}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts "Risk Level: #{data['risk_level']}"
puts "Reasons: #{data['reasons'].join(', ')}"
# Block HIGH and MEDIUM risk signups
if ['high', 'medium'].include?(data['risk_level'])
puts 'Signup blocked: Suspicious activity detected'
else
puts 'Signup allowed'
end
Risk Classification
How It Works
Mailbloc uses a straightforward 4-tier risk classification system that evaluates both email addresses and IP addresses independently, then combines them to give you a final risk assessment. The system is designed to catch fraud while minimizing false positives.
Email Classification Logic
- Disposable email check: We check if the domain is in our database of known disposable email providers (10k+ domains) → HIGH risk
- Privacy forwarding check: We detect email forwarding services like SimpleLogin, AnonAddy → MEDIUM risk
- Free provider check: We identify major free providers (Gmail, Yahoo, Outlook, etc.) → LOW risk
- MX validation: For everything else, we verify the domain has valid MX records:
- Valid MX records found → NONE risk (clean corporate email)
- No MX records → HIGH risk (invalid domain)
IP Classification Logic
- High-risk IPs: TOR exit nodes, known malicious IPs (Spamhaus DROP), recent attackers (AbuseIPDB 90-day window) → HIGH risk
- Medium-risk IPs: VPNs, datacenter IPs, week-old attack reports → MEDIUM risk
- Low-risk IPs: Older attack reports (30+ days old) → LOW risk
- Clean IPs: No matches in any threat database → NONE risk
Combining Email & IP Risk
When you provide both email and IP, Mailbloc combines the risks intelligently:
- HIGH risk always wins: If either email or IP is HIGH risk, the final result is HIGH
- MEDIUM risk is second priority: If one is MEDIUM and the other is not HIGH, result is MEDIUM
- Corporate email can upgrade LOW IP to NONE: A clean corporate email (with valid MX) can override a low-risk IP and result in NONE risk
- Free email downgrades NONE IP to LOW: A Gmail address will result in LOW risk even with a clean IP
Risk Levels
HIGH Risk
Action: Block immediately. These are clear fraud indicators.
Examples: Disposable emails (tempmail.com), TOR network IPs, malicious IPs from Spamhaus, invalid domains with no MX records.
MEDIUM Risk
Action: We strongly recommend blocking. These signups are suspicious.
Examples: Privacy forwarding services (SimpleLogin, AnonAddy), VPN users, datacenter IPs, recently reported IPs.
LOW Risk
Action: Acceptable quality. Typical consumer signups.
Examples: Free email providers (Gmail, Yahoo, Outlook), IPs with old abuse reports (30+ days).
NONE Risk
Action: Clean signup. No fraud indicators detected.
Examples: Corporate emails with valid MX records ([email protected]), clean residential IPs with no abuse history.
Reason Codes
The reasons array provides specific codes explaining why a risk level was assigned. Here are all possible reason codes:
| Reason Code | Risk Level | Description |
|---|---|---|
disposable_email |
HIGH | Email domain is a known disposable email provider |
invalid_email |
HIGH | Email domain has no valid MX records (cannot receive mail) |
criminal_network_ip |
HIGH | IP is on Spamhaus DROP list (known criminal networks) |
malicious_ip |
HIGH | IP is known for malicious activity (IPsum database) |
tor_network_ip |
HIGH | IP is a TOR exit node |
recent_attacker_ip |
HIGH | IP reported for attacks in last 90 days (AbuseIPDB) |
privacy_email |
MEDIUM | Email is a privacy forwarding service (SimpleLogin, AnonAddy) |
vpn_ip |
MEDIUM | IP is from a VPN provider |
datacenter_ip |
MEDIUM | IP belongs to a datacenter (not residential) |
week_attacker_ip |
MEDIUM | IP reported for attacks 7-30 days ago |
suspicious_ip |
MEDIUM | IP exhibits suspicious patterns |
free_email |
LOW | Email is from a free provider (Gmail, Yahoo, etc.) |
reported_ip |
LOW | IP has old abuse reports (30-90 days) |
old_attacker_ip |
LOW | IP reported for attacks over 30 days ago |
| Empty array | NONE | No risk indicators found (clean) |
Support
Contact Us
We're here to help with any questions or issues you may encounter. Our team typically responds within 24 hours.
Email Support
team@mailbloc.com
We're available Monday to Friday, 9am-5pm SGT