Metadata-Version: 2.4
Name: ayzal-guard
Version: 0.1.0
Summary: Official Python client for Ayzal Guard — Email Risk & IP Intelligence API
Author-email: Ayzal AI <support@ayzalai.com>
License: MIT
Project-URL: Homepage, https://ayzalai.com/guard
Project-URL: Repository, https://github.com/zeeqmir/ayzal-guard
Project-URL: Documentation, https://ayzalai.com/guard/kb
Keywords: email,validation,fraud,risk,disposable,ip,stripe,checkout
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# ayzal-guard

Official Python client for [Ayzal Guard](https://ayzalai.com/guard) — the Email Risk & IP Intelligence API.

Score email, IP, and velocity **before** your payment gateway so disposable addresses and botnets never reach Stripe, PayPal, or Adyen.

## Install

    pip install ayzal-guard

## Quick start

```python
import os
from ayzal_guard import AyzalGuard

guard = AyzalGuard(api_key=os.environ["AYZAL_GUARD_KEY"])

result = guard.check("user@example.com", client_ip="1.2.3.4")

if result.verdict in ("disposable", "invalid"):
    raise ValueError("Please use a real email address")

# Proceed to Stripe / PayPal / Adyen

Fail-open in a checkout flow
Never block sales because a risk API is down. is_safe() returns True on network errors, timeouts, and 429s.

python
safe = guard.is_safe(email, client_ip=client_ip)
if not safe:
    return {"error": "Please use a real email address"}, 400

What you get back
check() returns a CheckResult dataclass:

python
result = guard.check("test@mailinator.com")
print(result.verdict)     # 'disposable'
print(result.reason)      # 'blocklist_hit'
print(result.mx.has_mx)   # False
print(result.ip_risk)     # IpRisk(...) or None
Sync and async
Both clients are provided. Pick the one that matches your app.

python
# Sync (Flask, Django, scripts)
from ayzal_guard import AyzalGuard
guard = AyzalGuard(api_key="ag_live_...")
result = guard.check("user@example.com")

# Async (FastAPI, aiohttp, asyncio)
from ayzal_guard import AsyncAyzalGuard
guard = AsyncAyzalGuard(api_key="ag_live_...")
result = await guard.check("user@example.com")

Error handling
python
from ayzal_guard import AyzalGuard, AyzalGuardError

try:
    result = guard.check(email)
except AyzalGuardError as e:
    print(e.status, e.code, e.message)
Integration examples
Full checkout examples for Stripe, PayPal, Flask, FastAPI, Express, PHP, Rails, and custom gateways are in the Knowledge Base.

License
MIT
