mailrambo

Official Python client for the MailRambo email verification API.

One call answers one question - can I send to this address without bouncing? deliverable is True only when the mailbox is confirmed; catch-all, disposable and unverifiable addresses are False, with a reason you can branch on.

• Sync and asyncio clients, typed, one dependency (httpx)
• Automatic retries on 429/5xx with backoff
• Retry-safe batches (idempotency keys added for you)
• Free test keys (mr_test_...) - build and run CI without spending credits

Install

pip install mailrambo

Get a free API key (100 verifications/month, API on every plan) at mailrambo.com.

Quick start

from mailrambo import MailRambo

mr = MailRambo()  # reads MAILRAMBO_API_KEY

result = mr.verify("jane@acme.com")
if not result["deliverable"]:
    print("Don't send:", result["reason"])  # mailbox_not_found, disposable, catch_all, ...

Async

from mailrambo import AsyncMailRambo

async with AsyncMailRambo() as mr:
    result = await mr.verify("jane@acme.com")

Block fake signups (Django / FastAPI)

BLOCK = {"disposable", "mailbox_not_found", "invalid_syntax", "spamtrap"}

def is_allowed_signup(email: str) -> bool:
    try:
        return mr.verify(email)["reason"] not in BLOCK
    except MailRamboError:
        return True  # fail open: never lose a real user to a timeout

Fast mode for signup forms (free)

r = mr.verify("jane@gmial.com", mode="fast")  # < 1s, no credit
r["deliverable"]  # False = reject (invalid_syntax, possible_typo, disposable, no_mx); None = looks fine, mailbox not checked
r["suggestion"]   # "jane@gmail.com"

Repeat checks of the same address within 24 hours are also free (cached: True).

Full detail

r = mr.verify("jane@acme.com", detail=True)
r["detail"]["grade"]                 # "A"
r["detail"]["inbox_provider"]        # "Google Workspace"
r["detail"]["dns"]["dmarc_policy"]   # "reject"

Same price (1 credit).

Lists

rows = mr.verify_many(emails, name="Q4 import")   # any size, batches of 200, input order kept
good = [r["email"] for r in rows if r["deliverable"]]

# or manage batches yourself
batch_id = mr.create_batch(emails[:200], idempotency_key="import-42")["batch_id"]
batch = mr.wait_for_batch(batch_id)

Credits

mr.account()["credits_remaining"]  # free call

Errors

Every API error raises MailRamboError with status, code and message:

from mailrambo import MailRamboError

try:
    mr.verify(email)
except MailRamboError as e:
    if e.code == "insufficient_credits":
        ...  # top up at https://www.mailrambo.com/pricing

Test mode

Create a mr_test_... key on the API Keys page. No credits are used, and the answer depends on the part before the @:

mr.verify("deliverable@example.com")  # True,  "mailbox_exists"
mr.verify("disposable@example.com")   # False, "disposable"
mr.verify("catch_all@example.com")    # False, "catch_all"
mr.verify("anything@example.com")     # False, "mailbox_not_found"

Links

• API reference · OpenAPI spec
• Free email & DNS tools
• Pricing

MIT License