MailOdds

Python Email Validation with the MailOdds SDK

Install in one command. Validate single addresses or entire lists. SMTP verification, disposable detection, and catch-all detection included.

Contents

InstallSingle ValidationBulk ValidationError HandlingFAQ

Install

Install the MailOdds SDK from PyPI. No other dependencies required.

Terminal
pip install mailodds

Get your API key from the dashboard. The free tier includes 50 validations per month with no credit card required.

Single Email Validation

Validate one address at a time. The SDK performs syntax, DNS, and SMTP mailbox checks in a single call and returns a structured result.

Python
from mailodds import Configuration, EmailValidationApi

# Configure once, reuse the client
config = Configuration(host="https://api.mailodds.com")
config.access_token = "YOUR_API_KEY"

api = EmailValidationApi(config)
result = api.validate_email({"email": "user@example.com"})

print(result.status)       # "valid"
print(result.action)       # "accept"
print(result.disposable)   # False
print(result.role_account) # False
print(result.reason)       # "Mailbox exists and is deliverable"

Response fields

status — valid, invalid, catch_all, unknown, do_not_mail

action — accept, reject, accept_with_caution, retry_later

sub_status — detailed reason (e.g. mailbox_not_found, disposable)

disposable — boolean, True for throwaway providers

role_account — boolean, True for info@, support@, etc.

free_provider — boolean, True for Gmail, Yahoo, etc.

Bulk Validation

Upload a CSV, Excel, or plain text file and poll for completion. Results are available as CSV or JSON download when the job finishes.

Python
from mailodds import Configuration, BulkValidationApi
import time

config = Configuration(host="https://api.mailodds.com")
config.access_token = "YOUR_API_KEY"
bulk = BulkValidationApi(config)

# Upload a CSV file
with open("emails.csv", "rb") as f:
    job = bulk.create_job(file=f)

print(f"Job created: {job.id}")

# Poll until done
while True:
    status = bulk.get_job(job.id)
    print(f"Progress: {status.progress}%")
    if status.status == "completed":
        break
    time.sleep(5)

# Download results as CSV
results = bulk.download_results(job.id, format="csv")
print(f"Downloaded {len(results)} bytes")

Error Handling

The SDK raises typed exceptions so you can handle each failure case explicitly. Retries with exponential backoff are built in for transient errors.

Python
from mailodds import Configuration, EmailValidationApi
from mailodds.enterprise.errors import (
    InsufficientCreditsError,
    AuthenticationError,
    RateLimitError,
    MailOddsError,
)

config = Configuration(host="https://api.mailodds.com")
config.access_token = "YOUR_API_KEY"
api = EmailValidationApi(config)

try:
    result = api.validate_email({"email": "user@example.com"})
except InsufficientCreditsError:
    print("Out of credits, upgrade your plan")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit hit, SDK will retry automatically")
except MailOddsError as e:
    print(f"API error: {e}")

Frequently Asked Questions

Start validating emails in Python

Install the MailOdds SDK and validate your first email in under 2 minutes. Free tier included.

Quickstart Guide View All SDKs