How to build a Python email-checker using the Mail7 API (and spot disposable addresses like TempMailbox)

#!/usr/bin/env python3
"""
mail7_check.py
Simple utilities to check an email address using Mail7 Email Checker API.
"""

import time
import requests
from typing import Dict, Optional

BASE = "https://mail7.net"
SINGLE_ENDPOINT = f"{BASE}/api/validate-single"
BULK_ENDPOINT = f"{BASE}/api/validate-bulk"
SPF_ENDPOINT = f"{BASE}/api/spf-check/{{}}"

# Simple wrapper for single validation
def validate_single(email: str, timeout: float = 10.0) -> Dict:
    """Validate a single email. Returns the parsed JSON response."""
    payload = {"email": email}
    headers = {"Content-Type": "application/json"}
    while True:
        resp = requests.post(SINGLE_ENDPOINT, json=payload, headers=headers, timeout=timeout)
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code == 429:
            # Respect Retry-After header if present
            retry = resp.headers.get("Retry-After")
            wait = int(retry) if retry and retry.isdigit() else 60
            print(f"[rate-limit] 429 received. Waiting {wait} seconds...")
            time.sleep(wait)
            continue
        if 500 <= resp.status_code < 600:
            # transient server error, back off a bit
            print(f"[server-error] {resp.status_code}. Backing off 5s...")
            time.sleep(5)
            continue
        # For other errors, raise
        resp.raise_for_status()

def is_good_email(result: Dict) -> bool:
    """
    Heuristic to decide whether to accept this email:
      - result['valid'] should be True
      - smtpValid and mxValid are helpful
      - is_disposable should be False
      - status normally contains 'Valid' for good addresses
    Adapt this logic to your business needs.
    """
    if not result:
        return False
    if result.get("is_disposable"):
        return False
    # require overall valid + smtp existence
    if result.get("valid") and result.get("smtpValid"):
        return True
    # fallback: format + mx
    if result.get("formatValid") and result.get("mxValid"):
        return True
    return False

def pretty_print(result: Dict):
    print("email:", result.get("email"))
    print("status:", result.get("status"))
    print("valid:", result.get("valid"))
    print("formatValid:", result.get("formatValid"))
    print("mxValid:", result.get("mxValid"))
    print("smtpValid:", result.get("smtpValid"))
    print("is_disposable:", result.get("is_disposable"))
    print("details:", result.get("details"))

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser(description="Check email validity using mail7.net API")
    parser.add_argument("email", help="Email to check, or path to file with emails (one per line) if --bulk")
    parser.add_argument("--bulk", action="store_true", help="Treat argument as a file and run bulk check (calls validate-bulk)")
    args = parser.parse_args()

    if args.bulk:
        # Bulk mode: upload file to /api/validate-bulk (form data: 'emails')
        with open(args.email, "rb") as f:
            files = {"emails": (args.email, f)}
            r = requests.post(BULK_ENDPOINT, files=files)
            r.raise_for_status()
            data = r.json()
            print("Total:", data.get("total"))
            for item in data.get("results", []):
                print("----")
                pretty_print(item)
    else:
        res = validate_single(args.email)
        pretty_print(res)
        print("DECISION:", "ACCEPT" if is_good_email(res) else "REJECT")

pip install requests
python3 mail7_check.py [email to check]
# or bulk:
python3 mail7_check.py emails.txt --bulk