📧 BlockFakeMail API Documentation

Comprehensive Email Validation API with Detailed Response Properties

Table of Contents

Overview

The BlockFakeMail API provides comprehensive email validation with detailed analysis of email addresses. It performs multiple checks including syntax validation, DNS resolution, MX record verification, disposable domain detection, and local part heuristics to determine the legitimacy of an email address.

Base URL: https://BlockFakeMail.com

Authentication

All API calls require authentication. The BlockFakeMail API uses Bearer token authentication. You must include a valid API token in the Authorization header of every request.

Authentication Method

Include your API token in the request header using the Bearer authentication scheme:

Authorization: Bearer bfm_YOUR_API_TOKEN

Generating API Keys

To generate an API key, you need to:

  1. Register an account at https://BlockFakeMail.com
  2. Subscribe to a plan that includes API access
  3. Log in to get an access token
  4. Create an API token using the POST /api/tokens endpoint (see User Endpoints below)

The API token will be returned only once when created. Store it securely, as you won't be able to retrieve it again. API tokens are prefixed with bfm_ for easy identification.

Important: Keep your API tokens secure. Do not share them publicly or commit them to version control. If a token is compromised, delete it immediately and create a new one.

User Endpoints

These endpoints are available to authenticated users to manage their account, subscriptions, and API tokens.

Get Subscription Information

GET /api/subscription

Retrieve your current subscription details, including remaining API calls for the current billing cycle. This is essential for monitoring your API usage.

Response

{ "id": 1, "user_id": 1, "tier_id": 1, "status": "active", "current_period_start": "2024-01-01T00:00:00Z", "current_period_end": "2024-02-01T00:00:00Z", "api_calls_used_this_month": 150, "api_calls_limit_this_month": 1000, "billing_cycle_reset_at": "2024-02-01T00:00:00Z", "created_at": "2024-01-01T00:00:00Z" }
Property Type Description
api_calls_used_this_month integer The number of API calls you have made in the current billing cycle.
api_calls_limit_this_month integer The maximum number of API calls allowed per billing cycle based on your subscription tier.
billing_cycle_reset_at datetime When your usage counter will reset and a new billing cycle begins.
status string Subscription status: "active", "canceled", or "past_due".

Create API Token

POST /api/tokens

Create a new API token for authenticating API requests. The token is returned only once - store it securely.

Request Body

{ "name": "My API Token" // Optional: A descriptive name for the token }

Response

{ "id": 1, "name": "My API Token", "token": "bfm_abc123...", // Store this securely - shown only once "last_used_at": null, "created_at": "2024-01-01T00:00:00Z" }

List API Tokens

GET /api/tokens

List all API tokens associated with your account. Note that the actual token value is not returned for security reasons.

Response

[ { "id": 1, "name": "My API Token", "last_used_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-01T00:00:00Z" } ]

Delete API Token

DELETE /api/tokens/{token_id}

Delete an API token. Use this if a token has been compromised or is no longer needed.

List Available Subscription Tiers

GET /api/tiers

Get a list of available subscription tiers with pricing and API call limits. This endpoint does not require authentication.

Email Validation Endpoint

POST https://BlockFakeMail.com/api/validate

Validates an email address and returns detailed validation results with confidence scoring. Requires authentication - see Authentication section above.

Request Format

Request Body

{ "email": "[email protected]", "options": { "dns_timeout_ms": 1500, "allow_catch_all_test": false } }
Property Type Required Description
email string Required The email address to validate. Can be in any format (will be normalized automatically by lowercasing and trimming whitespace).
options object Optional Validation options to customize the validation process.
options.dns_timeout_ms integer Optional DNS lookup timeout in milliseconds. Controls how long the validator will wait for DNS responses before timing out. Default: 1500ms. Range: 100-10000ms.
options.allow_catch_all_test boolean Optional Whether to allow catch-all domain testing. Currently not implemented. Default: false.

Response Format

The API returns a comprehensive validation response with detailed information about the email address.

Error Codes

The API may return various HTTP status codes. Understanding these codes is essential for proper error handling in your application.

Status Code Description Response Body
400 Bad Request Returned when the request is malformed or contains invalid data.

Example: {"detail": "Invalid email format"}

Common causes: Missing required fields, invalid JSON, or email format that cannot be processed.
401 Unauthorized Returned when authentication fails or no authentication token is provided.

Example: {"detail": "Invalid API token"}

Common causes:
  • Missing Authorization header
  • Invalid or expired API token
  • Token format is incorrect

Solution: Verify your API token is correct and included in the Authorization header as Bearer bfm_YOUR_TOKEN
403 Forbidden Returned when the user does not have an active subscription.

Example: {"detail": "No active subscription found. Please subscribe to use the API."}

This means you need to subscribe to a plan before using the API. Visit https://BlockFakeMail.com to subscribe.
429 Too Many Requests Returned when you have exceeded your monthly API call limit.

Example: {"detail": "API call limit exceeded. You have used 1000 of 1000 calls this month."}

Your usage counter resets at the beginning of each billing cycle (see billing_cycle_reset_at in your subscription).

Solution:
  • Wait for the billing cycle to reset
  • Upgrade to a higher tier with more API calls
  • Check your usage with GET /api/subscription to monitor remaining calls
500 Internal Server Error Returned when an unexpected server error occurs.

Example: {"detail": "Internal server error"}

If this persists, please contact support.
Error Handling Best Practices:
  • Always check the HTTP status code before processing the response
  • For 401 errors, verify your API token is correct and not expired
  • For 429 errors, implement exponential backoff and monitor your usage
  • Log error responses for debugging purposes
  • Use GET /api/subscription to proactively check remaining calls before making requests

Response Properties

Detailed explanation of all properties in the validation response:

Property Type Description
input string The original email address as provided in the request. This is the exact input string before any normalization, preserving the original format including any capitalization or whitespace.
normalized string The normalized version of the email address used for validation. Normalization includes lowercasing the entire address and trimming leading/trailing whitespace. This is the canonical form used for all validation checks.
verdict enum The overall validation verdict, which is the primary result of the validation process. This is calculated based on the confidence score:

LIKELY_VALID - Confidence score 75-100. The email appears legitimate and likely belongs to a real user.

UNCERTAIN - Confidence score 40-74. The email could be legitimate or fake; additional verification may be needed.

LIKELY_GARBAGE - Confidence score 0-39. The email is likely fake, disposable, or invalid.
confidence integer (0-100) Confidence score from 0 to 100 indicating how likely the email is legitimate. Higher scores indicate higher confidence in the email's legitimacy.

Scoring Breakdown:
  • Base score: 50
  • Syntax pass: +15
  • Domain resolves: +10
  • MX records present: +15
  • Disposable domain: -40
  • Random-looking local part: -10 to -25 (depending on randomness level)
The score is clamped to the 0-100 range.
syntax_valid boolean Indicates whether the email address has valid RFC-compliant syntax. If false, the email format is invalid and validation stops early. Common syntax errors include missing @ symbol, invalid characters, consecutive dots, leading/trailing dots, or length violations.
syntax_errors array of strings List of standardized syntax error codes if syntax validation fails. Possible codes:
  • missing_at - The @ symbol is missing
  • multiple_at - Multiple @ symbols found
  • empty_parts - Local part or domain is empty
  • consecutive_dots - Two or more consecutive dots found
  • leading_trailing_dot - Dot at the beginning or end of local part or domain
  • local_part_too_long - Local part exceeds maximum length (64 characters)
  • domain_label_too_long - Domain label exceeds maximum length (63 characters)
  • length_exceeded - Total email length exceeds maximum (254 characters)
  • invalid_characters - Contains invalid characters
  • syntax_error - Generic syntax error
Empty array if syntax is valid.
dns_resolve boolean Indicates whether the domain has valid DNS A or AAAA records (i.e., the domain resolves to an IP address). This is a basic requirement for any functional domain. If false, the domain cannot be reached and is likely invalid or non-existent.
mx_records boolean Indicates whether the domain has Mail Exchange (MX) records configured in DNS. MX records are required for a domain to receive email. If false, the domain cannot receive email messages even if it resolves to an IP address. This is a critical check for email deliverability.
disposable_detected boolean Indicates whether the domain is known to be a disposable or temporary email service. Disposable email services (e.g., 10minutemail.com, tempmail.com, guerrillamail.com) are often used for one-time registrations and may not be suitable for important communications. The list of disposable domains is automatically updated every 3 hours from a GitHub repository.
free_email_provider boolean Indicates whether the domain belongs to a known free email service provider (e.g., Gmail, Outlook, Yahoo, ProtonMail, iCloud). These are legitimate email services but may indicate a personal rather than professional email address. This information can be useful for determining the context of the email address.
local_confidence float (0.0-1.0) or null Confidence score (0.0 to 1.0) for the legitimacy of the local part (the part before @). Higher values (closer to 1.0) indicate the local part appears legitimate and human-chosen. Lower values (closer to 0.0) suggest suspicious patterns like randomness, placeholders, or role accounts.

This score is calculated based on entropy analysis, digit ratios, and pattern detection. null if not calculated (e.g., when syntax is invalid and validation stops early).
local_confidence_flags array of strings List of flags indicating issues detected in the local part. Possible flags:
  • role_account - The local part appears to be a role-based account (e.g., info, admin, support)
  • placeholder - The local part appears to be a placeholder (e.g., test, example, demo)
  • high_digit_ratio - The local part has an unusually high ratio of digits to letters
  • low_entropy - The local part has low entropy (too simple or predictable)
  • random_pattern - The local part appears to be randomly generated (confidence > 0.5)
Empty array means no suspicious patterns were detected in the local part.
role_account boolean Indicates whether the local part appears to be a role-based account. Role accounts are generic addresses like 'info', 'admin', 'support', 'sales', 'noreply', 'contact', 'help', etc. These are often used for automated emails and may not be monitored by individuals. They are legitimate but may not be suitable for personal communications.
checks array of objects or null Array of individual validation checks performed. Each check object contains:
  • id - Check identifier: 'syntax', 'domain_dns', 'mx', 'disposable', or 'local_part'
  • status - Check status: 'pass', 'warn', 'fail', or 'skip'
  • message - Human-readable message describing the result
This provides detailed information about each validation step. Included for backward compatibility and UI support.
signals object Structured signals extracted during email validation. Contains domain information, TLD, and detected characteristics. See the Signals Object section for detailed information.
timings_ms object Performance timing information in milliseconds. Contains:
  • total - Total validation time from request start to response generation
  • dns - Time spent on DNS lookups (domain resolution and MX records)
Useful for monitoring API performance. Typical validation times are under 200ms.

Signals Object

The signals object contains structured information extracted during validation:

Property Type Description
domain_name string The email domain part (e.g., 'gmail.com', 'company.org'). This is the part after the @ symbol, extracted and normalized.
top_level_domain string The domain extension (e.g., 'com', 'org', 'net', 'edu', 'io'). This is the last part of the domain after the final dot.
role_account_detected boolean True if the local part (before @) appears to be a role-based account like 'info', 'admin', 'support', 'sales', or 'noreply'. These are often used for automated emails and may not be monitored by individuals. This is the same value as the top-level role_account property.
free_email_provider_detected boolean True if the domain is a known free email service provider (e.g., Gmail, Outlook, Yahoo, ProtonMail). These are legitimate but may indicate a personal rather than professional email address. This is the same value as the top-level free_email_provider property.
disposable_domain_detected boolean True if the domain is known to be a disposable or temporary email service. These services are often used for one-time registrations and may not be suitable for important communications. This is the same value as the top-level disposable_detected property.
mail_exchange_records_present boolean True if the domain has MX (Mail Exchange) records configured in DNS. This indicates the domain is set up to receive email. Domains without MX records cannot receive email. This is the same value as the top-level mx_records property.

Validation Checks

The validation process performs the following checks in order:

1. Syntax Check

Validates the email format according to RFC standards. Checks for proper structure, valid characters, and length constraints.

2. Domain DNS Check

Verifies that the domain has valid A or AAAA DNS records, meaning it resolves to an IP address.

3. MX Records Check

Checks for Mail Exchange (MX) records, which are required for the domain to receive email.

4. Disposable Domain Check

Checks against an automatically-updated list of known disposable email service domains.

5. Local Part Heuristics

Analyzes the local part (before @) for suspicious patterns including role accounts, placeholders, randomness, and entropy.

Examples

Example Request

curl -X POST "https://BlockFakeMail.com/api/validate" \ -H "Authorization: Bearer bfm_YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "options": { "dns_timeout_ms": 1500 } }'

Example Response - Valid Email

{ "input": "[email protected]", "normalized": "[email protected]", "verdict": "LIKELY_VALID", "confidence": 90, "syntax_valid": true, "syntax_errors": [], "dns_resolve": true, "mx_records": true, "disposable_detected": false, "free_email_provider": true, "local_confidence": 0.85, "local_confidence_flags": [], "role_account": false, "checks": [ { "id": "syntax", "status": "pass", "message": "RFC-like format looks valid" }, { "id": "domain_dns", "status": "pass", "message": "Domain resolves (A/AAAA)" }, { "id": "mx", "status": "pass", "message": "MX records found" }, { "id": "disposable", "status": "pass", "message": "Domain is not disposable" }, { "id": "local_part", "status": "pass", "message": "Local part looks legitimate" } ], "signals": { "domain_name": "gmail.com", "top_level_domain": "com", "role_account_detected": false, "free_email_provider_detected": true, "disposable_domain_detected": false, "mail_exchange_records_present": true }, "timings_ms": { "total": 143, "dns": 33 } }

Example Response - Disposable Email

{ "input": "[email protected]", "normalized": "[email protected]", "verdict": "LIKELY_GARBAGE", "confidence": 25, "syntax_valid": true, "syntax_errors": [], "dns_resolve": true, "mx_records": true, "disposable_detected": true, "free_email_provider": false, "local_confidence": 0.3, "local_confidence_flags": ["placeholder"], "role_account": false, "checks": [ { "id": "syntax", "status": "pass", "message": "RFC-like format looks valid" }, { "id": "domain_dns", "status": "pass", "message": "Domain resolves (A/AAAA)" }, { "id": "mx", "status": "pass", "message": "MX records found" }, { "id": "disposable", "status": "warn", "message": "Domain appears disposable" }, { "id": "local_part", "status": "warn", "message": "Local part may be a placeholder" } ], "signals": { "domain_name": "10minutemail.com", "top_level_domain": "com", "role_account_detected": false, "free_email_provider_detected": false, "disposable_domain_detected": true, "mail_exchange_records_present": true }, "timings_ms": { "total": 156, "dns": 45 } }

Example Response - Invalid Syntax

{ "input": "invalid.email", "normalized": "invalid.email", "verdict": "LIKELY_GARBAGE", "confidence": 0, "syntax_valid": false, "syntax_errors": ["missing_at"], "dns_resolve": false, "mx_records": false, "disposable_detected": false, "free_email_provider": false, "local_confidence": null, "local_confidence_flags": [], "role_account": false, "checks": [ { "id": "syntax", "status": "fail", "message": "Missing @ symbol" } ], "signals": { "domain_name": "", "top_level_domain": "", "role_account_detected": false, "free_email_provider_detected": false, "disposable_domain_detected": false, "mail_exchange_records_present": false }, "timings_ms": { "total": 2, "dns": 0 } }
Note: FastAPI also provides interactive API documentation at /docs (Swagger UI) and /redoc (ReDoc) endpoints. These provide interactive testing capabilities and are automatically generated from the API schema.