Email validation · Integrations · Python
Integration guide
Email validation in Python.
In this guide
How do I validate an email with Python?
No SDK to install. requests or httpx, whichever your project already depends on.
Python, with requests
import os
import requests
API = "https://api.trueguard.io/v2/email/validation"
def validate_email(email: str) -> dict:
res = requests.post(
API,
headers={"X-API-KEY": os.environ["TRUEGUARD_KEY"]},
json={"email": email},
timeout=5,
)
res.raise_for_status()
return res.json()
result = validate_email("founder@yourcompany.com")
if result["deliverability"]["status"] == "invalid":
# reject the submission
...One header, one body field
Set X-API-KEY to your key and POST a JSON body with a single email field. HTTPS only. The response carries the seven signals plus one deliverability status.
Response fields you will branch on
deliverability.statussafe, risky, invalid or unknown. This is the field to branch on.
syntax.isValidRFC 5322 format check. Deterministic, so a false here is always a typo or a malformed address.
quality.isDisposableTrue for throwaway providers. Usually a hard block at signup.
deliverability.isCatchallTrue when the domain accepts any address. The status is then risky, unless a second check confirmed or ruled out the mailbox.
quality.isRoleinfo@, support@, sales@. Route these differently rather than rejecting them.
Run it once before you write any code.
The same endpoint the snippet above calls. 10 free checks a day, no key needed.
Or try
Where should the call live in a Python app?
Your API key is a secret. Where you put this call decides whether it stays one.
In a template or client-facing view
Do not put the key anywhere that reaches the client, and do not call the endpoint inline in a template render. Keep it in a service function your view calls, with the key read from the environment.
In a service module, called from your view
A Django form's clean method, a DRF serializer validator or a FastAPI dependency are all good homes. The key stays server-side in an environment variable and you branch on the status before the record is saved.
What the endpoint returns
{
"email": "founder@yourcompany.com",
"rawEmail": "founder@yourcompany.com",
"syntax": { "isValid": true },
"deliverability": {
"status": "safe",
"isSmtpValid": true,
"isMxValid": true,
"isCatchall": false,
"isInboxFull": false,
"isDeliverable": true,
"isDisabled": false,
"mxRecords": ["mx1.yourcompany.com", "mx2.yourcompany.com"]
},
"domain": {
"name": "yourcompany.com",
"age": 2841,
"isLive": true,
"isRisky": false
},
"quality": {
"isDisposable": false,
"isFree": false,
"isRole": false,
"isSubaddress": false
}
}How do I handle errors and rate limits in Python?
from requests import HTTPError, Timeout
try:
result = validate_email(email)
except HTTPError as err:
status = err.response.status_code
if status == 429:
# quota or rate limit: allow with a flag
return allow_with_flag(email)
if status == 401:
logger.error("Trueguard key rejected")
return allow_with_flag(email)
except Timeout:
return allow_with_flag(email)Status
What to do
200Validation ran. Read deliverability.status and branch.
400Malformed request body. Check you are sending JSON with an email field.
401Missing or rejected API key. Log it loudly: every request is failing.
429Rate limit or monthly quota reached. Allow the user through with a flag and alert yourself; do not block real signups on your own quota.
5xxRetry once with a short backoff, then fall back to allowing with a flag.
Which Python frameworks does this work with?
It is one HTTPS request, so anything that can make one works. These are the stacks people ask about.
Django form validation
FastAPI dependency
pandas list cleaning
Nightly re-check with Celery
What it costs once you ship.
Three tiers. The free plan needs no card and runs the production endpoint.
Standard
Popular$49.99 / month
50,000 validations / month
Overage: $0.001 per validation
Get your API keyFrequently asked questions
The full field reference lives in the API documentation.
requests or httpx?
Either. requests is the shortest path in a synchronous view; httpx is the better fit inside FastAPI or anything async, because it will not block the event loop.
Where does this belong in Django?
In a service function called from the form's clean method or a serializer validator, so the verdict is available before the model is saved and the error surfaces on the field the user can fix.
How do I validate a whole CSV?
Loop the column and call the endpoint per row, with a small concurrency limit and a retry on 429. A 50,000-row list fits inside the Standard plan quota; there is no bulk upload endpoint.
What timeout should I set?
Around 5 seconds. Median response is under a second, but SMTP checks wait on the destination server. On timeout, allow the record with a flag rather than blocking a real user.
Is there an official Python SDK?
No. The endpoint is one POST with one header and one body field, so a ten-line function covers it and there is no dependency to keep up to date.
The same guide, other stacks
Validate emails from Python in minutes.
100 validations a month, free, no card. Working code above, production endpoint, same response shape on every plan.
Get your free API keyNo credit card required.
