API Reference

Base URL: https://email.ayzalai.com

POST /v1/check/email

Check a single email against the risk engine.

Headers

Header	Required	Description
`X-API-Key`	yes	Your API key
`Content-Type`	yes	`application/json`

Request body

{
  "email": "user@example.com",
  "client_ip": "203.0.113.42"
}

Field	Type	Required	Description
`email`	string	yes	Email address to check
`client_ip`	string	no	End user’s IP. Falls back to `X-Forwarded-For` header if omitted

Response `200 OK

{
  "email": "test@mailinator.com",
  "canonical": "test@mailinator.com",
  "normalizations": [],
  "verdict": "disposable",
  "reason": "blocklist_hit",
  "domain": "mailinator.com",
  "local_part": "test",
  "mx": { "has_mx": false, "hosts": [], "fingerprint_match": null },
  "canonical_velocity": { "prior_count": 0, "window_seconds": 86400, "threshold": 10, "is_elevated": false },
  "ip_risk": {
    "country": "US", "is_proxy": true, "is_vpn": false, "is_tor": false,
    "fraud_score": 75, "is_datacenter": true
  },
  "flags": { "disposable": true, "role_account": false, "plus_alias": false, "mx_fingerprint": false }
}

Verdicts

Verdict	Meaning	Recommended action
`ok`	Email passed all checks	Proceed to payment
`disposable`	On blocklist or MX-host fingerprint match	Block
`invalid`	Syntax failed or no MX records	Block
`suspicious`	Velocity threshold exceeded or high-risk IP	Block or flag for manual review

Reason codes

`reason`	Meaning
`null`	No issue (only when `verdict = "ok"`)
`invalid_syntax`	Email format failed regex
`blocklist_hit`	Domain on disposable list
`no_mx_records`	Domain has no MX records
`mx_fingerprint_match`	MX host matches a known disposable mail provider
`canonical_velocity_exceeded`	Same canonical email seen above threshold within window

Error responses

Status	Body	Meaning
`401`	`{"detail": "Missing X-API-Key header..."}`	No key
`401`	`{"detail": "Invalid or revoked API key"}`	Bad key
`429`	`{"detail": "Monthly quota exceeded..."}`	Quota hit
`500`	`{"detail": "Internal server error"}`	Retry with backoff

GET /v1/check/email

Same as POST, with query params:

GET /v1/check/email?email=user@example.com&client_ip=203.0.113.42

GET /v1/health

Public health check. No auth.

{"status": "ok", "redis": true}

GET /v1/public/demo-key

Public demo key for the landing widget. Rate-limited per IQ (20/hour).

{
  "key": "ag_demo_...",
  "prefix": "ag_demo_xxxx",
  "monthly_limit": 100000
}