emailsherlock-sdk

Official Python client for the EmailSherlock email-verification API. Verify one address or a batch over HTTPS with an API key. Get an API key at https://emailsherlock.com/api. Want to try a single address by hand first? The free email verification tool runs the same checks in the browser.

Zero third-party dependencies (uses only the standard library). Python 3.8+.

Install

pip install emailsherlock-sdk

The distribution is emailsherlock-sdk; the import is emailsherlock:

from emailsherlock import Emailsherlock

Quick start

import os
from emailsherlock import Emailsherlock

# reads the key from the environment, never hard-code it
es = Emailsherlock(api_key=os.environ["ES_KEY"])

result = es.verify.single(email="jane@acme.com")

print(result.result)  # "valid"
print(result.score)   # 0.95

Called with no argument, Emailsherlock() reads ES_KEY (or EMAILSHERLOCK_API_KEY) from the environment.

Batch

Up to 100 addresses per call:

batch = es.verify.batch(emails=["jane@acme.com", "sales@acme.com"])

for item in batch.results:
    if isinstance(item, VerifyResult):
        print(item.email, item.result)
    else:  # BatchItemError
        print(item.email, "failed:", item.error)

The result object

VerifyResult mirrors the API JSON:

The fields from deliverable down are additive: they are None on older API responses and may be null per field when a signal has not been measured yet.

Domain intelligence

When the API returns a domain object, result.domain is a VerifyDomain:

result = es.verify.single(email="jane@acme.com")

if result.domain is not None:
    print(result.domain.score)         # 87.0
    print(result.domain.dmarc_policy)  # "reject"

Credits and rate limits

After every call:

es.credits_remaining   # e.g. 41
es.rate_limit          # {"limit": 60, "remaining": 59, "reset": 1700000000}

Errors

Every failure raises a subclass of EmailsherlockError:

from emailsherlock import RateLimitError

try:
    es.verify.single(email="jane@acme.com")
except RateLimitError as err:
    print(f"retry after {err.retry_after}s")

License

MIT. Full API reference: https://emailsherlock.com/api/docs