How to validate emails in Python using the OhBounce.ai API
A step-by-step guide to integrating email validation into a Python application — covering single-address validation, bulk jobs, and handling the async polling pattern with asyncio.
Python is among the most common languages our API is called from — whether in Django sign-up views, FastAPI endpoints, or data pipeline scripts processing CSV uploads. This guide covers all three patterns.
Single-address validation
For real-time validation in a web handler, use the requests library. Make a POST to /api/v1/validate with your API key in the Authorization header and the email in the JSON body. The response comes back synchronously — typically in under 200ms. Check the status field: VALID means safe to proceed, anything else should be handled per your business rules.
Bulk validation with asyncio
For processing large lists, use the bulk endpoint. Submit your list with a POST to /api/v1/validate/bulk and receive a jobId in the response. Then poll GET /api/v1/jobs/:jobId on an interval until the status is COMPLETED. With Python's asyncio and httpx, you can poll without blocking the event loop — useful when processing multiple bulk jobs in parallel.
Handling pagination on bulk results
Bulk results are paginated at 50 records per page. Loop through pages by incrementing the page query parameter until you've collected all records. For a 10,000-address job that's 200 pages — easy to handle in a simple while loop. Write results incrementally to a file or database rather than accumulating them all in memory.
CSV processing pattern
A common use case is reading a CSV of email addresses, validating the whole list, and writing a new CSV with a status column appended. Read the CSV with pandas or the built-in csv module, extract the email column, submit as a bulk job, poll until complete, fetch all result pages, and write the enriched output. The entire workflow for a 50,000-address CSV typically takes under two minutes.
Always store your API key in an environment variable, never hardcoded in source code. Use python-dotenv or your platform's secret manager.