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.

Pro Tip: You can validate just an email, just an IP, or both together. The API will classify risk based on whatever data you provide.

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

  1. Disposable email check: We check if the domain is in our database of known disposable email providers (10k+ domains) → HIGH risk
  2. Privacy forwarding check: We detect email forwarding services like SimpleLogin, AnonAddy → MEDIUM risk
  3. Free provider check: We identify major free providers (Gmail, Yahoo, Outlook, etc.) → LOW risk
  4. 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

  1. High-risk IPs: TOR exit nodes, known malicious IPs (Spamhaus DROP), recent attackers (AbuseIPDB 90-day window) → HIGH risk
  2. Medium-risk IPs: VPNs, datacenter IPs, week-old attack reports → MEDIUM risk
  3. Low-risk IPs: Older attack reports (30+ days old) → LOW risk
  4. 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

Pro users get priority support with faster response times.