Skip to content
Mail7

REST API

Email Checker API

One POST, one JSON body, one honest status. The API returns the same three answers as the site: Valid, Not Valid or Unknown, plus the mail server's own words behind each one.

Base URL

https://mail7.net

Auth header

X-API-Key: mk_live_...

An API key is free: create an account, confirm your email address, and generate one. Plans differ by monthly volume and request rate, not by whether the API is available.

Get a free key See plans

Base URL & Authentication

Base URL

https://mail7.net

Authentication - a confirmed account is all you need

Programmatic access needs an API key. Every plan includes one, the Free plan too: register, confirm your email address, then generate a key in your account. Confirmation is what the key is tied to, so a key can be traced to a real account and rate-limited fairly. Pass it in the X-API-Key header:

X-API-Key: mk_live_your_key_here

Prefer not to code? The web tools - single and bulk checks - stay free.

Create a free account Generate a key

Rate Limiting

Without a key you are limited by IP, and small daily budgets apply (per network and per recipient domain) - they exist to stop scripted abuse of the free endpoint. With a key the limit is per account with no daily budgets, and that is the main reason to create one even on the Free plan.

Request rate by caller
CallerRate
No key, by IP5 / min, 20 / day
Free, with a key20 / min
Starter30 / min
Pro120 / min
Business600 / min

Going over the limit returns HTTP 429 with a Retry-After header telling you when to try again. The rate cap is separate from your monthly quota: only definite Valid and Not Valid results count against that, Unknown ones are free.

Single Email Validation

Endpoint

POST /api/validate-single

Request Body

json
{
  "email": "[email protected]"
}

Response

json
{
  "email": "[email protected]",
  "valid": true,
  "formatValid": true,
  "mxValid": true,
  "smtpValid": true,
  "status": "Valid",
  "error": null,
  "details": "Email validation result: Valid - Email exists - accepted by alt3.gmail-smtp-in.l.google.com",
  "mx_servers": [
    "alt3.gmail-smtp-in.l.google.com",
    "alt1.gmail-smtp-in.l.google.com",
    "alt4.gmail-smtp-in.l.google.com",
    "alt2.gmail-smtp-in.l.google.com",
    "gmail-smtp-in.l.google.com"
  ],
  "smtp_message": "Email exists - accepted by alt3.gmail-smtp-in.l.google.com",
  "is_disposable": false
}

Response Fields

Basic Validation

  • email: The email address that was validated
  • valid: true = deliverable, false = does not exist, null = Unknown (could not be verified - see status). Do not treat Unknown as invalid.
  • formatValid: Whether the email format is correct (true/false)
  • mxValid: Whether MX records exist for the domain (true/false)
  • smtpValid: Whether the email exists on the server (true/false)

Status & Details

  • status: Human-readable status: "Valid", "Not Valid", or "Unknown" (address exists but cannot be reliably verified - e.g. disposable, catch-all, or greylisted)
  • error: Error message if validation failed (null if successful)
  • details: Detailed validation result description

Technical Details

  • mx_servers: Array of MX server hostnames
  • smtp_message: SMTP server response message
  • is_disposable: Whether the email is from a disposable email service (true/false)
  • flags: List-hygiene notes about the address: role, disposable, typo, catch_all, free_provider, no_probe. Each carries a label, a detail and the source it came from. A flag never changes the status: it describes a property of the address, not the answer. Mail7 does not report spam traps, because from the outside nobody can: a trap is a property of the relationship between an address and someone's list, and a recycled trap accepts mail and is honestly Valid.

Example with cURL

bash
curl -X POST https://mail7.net/api/validate-single \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Bulk Email Validation

Endpoint

POST /api/validate-bulk

Request (Form Data)

Send either a file or text list:

File Upload

bash
curl -X POST https://mail7.net/api/validate-bulk \
  -F "[email protected]"

Text List

bash
curl -X POST https://mail7.net/api/validate-bulk \
  -F "[email protected]
[email protected]
[email protected]"

Response

json
{
  "total": 3,
  "results": [
    {
      "email": "[email protected]",
      "valid": true,
      "formatValid": true,
      "mxValid": true,
      "smtpValid": true,
      "status": "Valid",
      "error": null,
      "details": "Email validation result: Valid - Email exists - accepted by alt3.gmail-smtp-in.l.google.com",
      "mx_servers": [
        "alt3.gmail-smtp-in.l.google.com",
        "alt1.gmail-smtp-in.l.google.com"
      ],
      "smtp_message": "Email exists - accepted by alt3.gmail-smtp-in.l.google.com",
      "is_disposable": false
    },
    {
      "email": "[email protected]",
      "valid": false,
      "formatValid": false,
      "mxValid": false,
      "smtpValid": false,
      "status": "Not Valid",
      "error": "Invalid email format",
      "details": "Email address format is invalid",
      "mx_servers": [],
      "smtp_message": "Format validation failed",
      "is_disposable": false
    }
  ]
}

SPF Record Check

Endpoint

GET /api/spf-check/{domain}

Parameters

domain string (path parameter)

The domain name to check SPF record for (e.g., "example.com")

Response

json
{
  "domain": "example.com",
  "is_valid": true,
  "spf_record": "v=spf1 include:_spf.google.com ~all",
  "dns_lookups": 1,
  "syntax_valid": true,
  "has_soft_fail": true,
  "has_hard_fail": false,
  "issues": [
    {
      "type": "warning",
      "message": "High DNS Lookup Count",
      "description": "SPF record causes 8 DNS lookups (close to limit of 10)",
      "recommendation": "Consider optimizing your SPF record to reduce DNS lookups",
      "severity": 2
    }
  ],
  "recommendations": [
    "Your SPF record is properly formatted and follows best practices.",
    "Consider implementing DKIM and DMARC alongside SPF for complete email authentication."
  ],
  "timestamp": "2025-01-01T12:00:00Z"
}

Example with cURL

bash
curl -X GET https://mail7.net/api/spf-check/example.com

Response Fields

Basic Information

  • domain: The domain that was checked
  • is_valid: Overall validity of the SPF record
  • spf_record: The actual SPF record found in DNS
  • timestamp: When the check was performed

Technical Details

  • dns_lookups: Number of DNS queries required (max 10)
  • syntax_valid: Whether the SPF syntax is correct
  • has_soft_fail: Presence of ~all mechanism
  • has_hard_fail: Presence of -all mechanism

Issues & Recommendations

  • issues: Array of detected problems with severity levels
  • recommendations: Actionable advice to fix issues

Health Check

Endpoint

GET /health

Response

json
{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00.123456"
}

Example

bash
curl https://mail7.net/health

Error Responses

Rate Limit Exceeded (429)

json
{
  "detail": "Rate limit exceeded. Maximum 5 requests per minute. Try again in 45 seconds.",
  "headers": {
    "Retry-After": "45",
    "X-RateLimit-Remaining": "0"
  }
}

Invalid Request (400)

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

Server Error (500)

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

HTTP Status Codes

200 Success
400 Bad Request
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

SDK Examples

JavaScript/Node.js

javascript
// Single email validation
const response = await fetch('https://mail7.net/api/validate-single', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]'
  })
});

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

// Bulk validation
const formData = new FormData();
formData.append('emails', '[email protected]\[email protected]');

const bulkResponse = await fetch('https://mail7.net/api/validate-bulk', {
  method: 'POST',
  body: formData
});

const bulkResult = await bulkResponse.json();
console.log(bulkResult);

// SPF record check
const spfResponse = await fetch('https://mail7.net/api/spf-check/example.com');
const spfResult = await spfResponse.json();
console.log(spfResult);

Python

python
import requests
import json

# Single email validation
response = requests.post('https://mail7.net/api/validate-single', 
    json={'email': '[email protected]'})
result = response.json()
print(result)

# Bulk validation
emails = "[email protected]\[email protected]"
files = {'emails': (None, emails)}
response = requests.post('https://mail7.net/api/validate-bulk', files=files)
result = response.json()
print(result)

# SPF record check
spf_response = requests.get('https://mail7.net/api/spf-check/example.com')
spf_result = spf_response.json()
print(spf_result)

PHP

php
// Single email validation
$data = ['email' => '[email protected]'];
$options = [
    'http' => [
        'header' => "Content-type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents('https://mail7.net/api/validate-single', false, $context);
$response = json_decode($result, true);
print_r($response);

// SPF record check
$spf_context = stream_context_create([
    'http' => [
        'method' => 'GET'
    ]
]);
$spf_result = file_get_contents('https://mail7.net/api/spf-check/example.com', false, $spf_context);
$spf_response = json_decode($spf_result, true);
print_r($spf_response);