email-validator

email-validator is an opinionated Python library that checks whether a string is a well-formed, deliverable email address. It validates syntax against RFC rules, supports internationalized domain names and local parts, and optionally performs DNS-based deliverability checks (MX/A/AAAA records) so applications can reject unreachable domains before storing them.

Beyond a pass/fail check, it returns a normalized form of the address that should be stored and compared going forward, along with structured fields like the ASCII-ized form, display name, and parsed domain-literal IP addresses when applicable. It deliberately rejects obsolete or unsafe address forms (special-use domains, unsafe Unicode) that would otherwise cause grief in registration and login flows.

What You Get

• validate_email() returning a normalized address plus ASCII-ized, display-name, and domain-literal fields
• EmailSyntaxError and EmailUndeliverableError exception classes (both subclasses of EmailNotValidError/ValueError) with friendly, end-user-displayable messages
• Optional DNS-based deliverability checks (MX record lookup with A/AAAA fallback) via a pluggable dns.resolver.Resolver
• A caching_resolver() helper for reusing DNS lookups across many validations with a timeout and LRU cache
• Support for internationalized domain names (IDNA 2008) and internationalized/quoted local parts
• Configurable options for quoted-local-parts, domain literals, display names, empty local parts, and stricter RFC compliance

Common Use Cases

• Validating email addresses on account registration forms before writing them to a database
• Normalizing stored email addresses so duplicate-detection and login lookups are consistent
• Skipping DNS checks on login forms (check_deliverability=False) while enforcing them at signup
• Accepting internationalized email addresses (non-ASCII domains and local parts) correctly
• Allowing test-only @test/@*.test domains in non-production environments via test_environment=True

Under The Hood

Architecture: The library is a small, focused pipeline: syntax.py implements RFC-5321/5322/6531-aware parsing of the local part and domain, rfc_constants.py centralizes the character-class and length constants those checks rely on, deliverability.py performs the optional DNS MX/A/AAAA lookups through a caller-supplied or default dns.resolver.Resolver, and validate_email.py in email_validator/ orchestrates the two stages and assembles the returned ValidatedEmail object defined in types.py. exceptions.py defines the EmailNotValidError hierarchy consumed by callers.

Tech Stack: Pure Python 3.10+ with dnspython and idna as the only meaningful runtime dependencies (for DNS resolution and IDNA 2008 domain encoding respectively). Packaged with setuptools/pyproject.toml, distributed as a universal wheel, and ships py.typed for full type-annotation support in consuming codebases.

Code Quality: tests/test_syntax.py, tests/test_deliverability.py, and tests/test_main.py cover syntax edge cases (IDN, quoted locals, domain literals), DNS-check behavior, and CLI usage; CI runs them via GitHub Actions (test_and_build.yaml) across supported Python versions. Error paths are modeled as typed exceptions with descriptive messages rather than generic ValueErrors, and the codebase is fully type-annotated.

API Design: The primary entry point is a single function, validate_email(email, **options), with all behavior controlled by well-documented keyword arguments and module-level defaults (e.g. email_validator.CHECK_DELIVERABILITY) that can be set once for an app. This keeps the common case (‘is this address valid, and what’s its normalized form’) to two or three lines, while advanced options (quoted locals, domain literals, custom resolvers) stay opt-in rather than cluttering the default call.