Python SDK

Official Python SDK for the Truelist email validation API. Sync and async clients, full type annotations, and minimal dependencies.

Installation

pip install truelist

Requires Python 3.9+.

Quick start

from truelist import Truelist

client = Truelist("your-api-key")
result = client.email.validate("user@example.com")
print(result.state)      # "ok"
print(result.is_valid)   # True

Async usage

from truelist import AsyncTruelist

async with AsyncTruelist("your-api-key") as client:
    result = await client.email.validate("user@example.com")

Configuration

client = Truelist(
    "your-api-key",
    base_url="https://api.truelist.io",
    timeout=30.0,
    max_retries=2,
)

ValidationResult fields

Convenience properties: is_valid, is_invalid, is_risky, is_unknown, is_disposable, is_role

Error handling

from truelist import AuthenticationError, RateLimitError, ApiError

try:
    result = client.email.validate("user@example.com")
except AuthenticationError:
    print("Check your API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ApiError as e:
    print(f"API error {e.status_code}: {e.message}")

Account info

account = client.account.get()
print(account.email)        # "you@company.com"
print(account.payment_plan) # "pro"

Django integration

pip install truelist-django
# With DRF support:
pip install "truelist-django[drf]"

Add your API key to settings:

# settings.py
TRUELIST_API_KEY = "your-api-key"

Model validator

from truelist_django.validators import TruelistEmailValidator

class User(models.Model):
    email = models.EmailField(
        validators=[TruelistEmailValidator(allow_risky=True, fail_silently=True)]
    )

DRF serializer field

from truelist_django.fields import TruelistEmailField

class SignupSerializer(serializers.Serializer):
    email = TruelistEmailField(allow_risky=False, fail_silently=True)

Django settings

Caching

TRUELIST_CACHE_ENABLED = True
TRUELIST_CACHE_TTL = 3600

Uses Django’s cache framework. Unknown results are never cached.

Package links