Metadata-Version: 2.4
Name: mailValidator
Version: 0.3.0.0
Summary: Verify email addresses via DNS and SMTP, with disposable/temp-mail domain detection.
Author-email: Anu T <mail2packagehandler@gmail.com>
Maintainer-email: Anu T <mail2packagehandler@gmail.com>
License: Proprietary
Project-URL: Homepage, https://pypi.org/project/mailValidator/
Project-URL: Changelog, https://pypi.org/project/mailValidator/
Project-URL: Documentation, https://pypi.org/project/mailValidator/
Keywords: email,validation,smtp,dns,disposable,mail
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Email
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: dnspython>=2.0.0
Requires-Dist: python-dotenv>=0.21.0
Requires-Dist: xlsxwriter>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# mailValidator

[![PyPI version](https://badge.fury.io/py/mailValidator.svg)](https://pypi.org/project/mailValidator/)
[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)

**Version:** 0.2.7.0

Python package to verify email addresses using DNS and SMTP checks, with disposable/temp-mail domain detection, catch-all detection, and a CLI.

## Features

- **DNS verification** — resolves MX records (with A/AAAA fallback per RFC 5321)
- **SMTP verification** — validates mailboxes without sending email
- **Disposable/temp-mail detection** — bundled blocklist (~72k domains); early `202` response skips DNS/SMTP for known domains
- **Catch-all detection** — status `201` when a domain accepts all addresses
- **Organization policy blocks** — status `203` when SMTP servers block external verification
- **Whitelist/blacklist** — configurable email and domain lists
- **CLI** — batch validation with grouped or table output; export to `.txt` or `.xlsx`
- **Python API** — `verify_email()` and `verify_emails_list()`

## Installation

```bash
pip install mailValidator
```

For development:

```bash
git clone <repository-url>
cd emailValidator
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Quick start

### CLI

```bash
mailValidator --emails user@example.com,test@mailinator.com --format table
```

```bash
mailValidator --emails emails.txt --output results.txt --timeout 10
mailValidator --emails emails.txt --format table --output results.xlsx
```

### Python

```python
from mailValidator import verify_email

print(verify_email("user@example.com"))
# {'status': '200', 'message': 'Valid email'}

print(verify_email("test@mailinator.com"))
# {'status': '202', 'message': 'Valid email but domain is temporary/disposable.'}
```

## CLI reference

| Option | Description |
|--------|-------------|
| `--emails` | Comma-separated emails or path to a `.txt` file (one email per line) |
| `--timeout` | SMTP timeout in seconds (default: 5) |
| `--output` | Save results to `.txt` or `.xlsx` |
| `--format` | `grouped` (default) or `table` (Email \| Status \| Message) |

## Response model

Every validation returns a dict:

```python
{"status": "<code>", "message": "<description>"}
```

| Status | Meaning |
|--------|---------|
| **200** | Valid email (SMTP accepted or whitelisted) |
| **201** | Valid email, but domain is a catch-all |
| **202** | Disposable/temp-mail domain (checked early; DNS/SMTP skipped for blocklisted domains) |
| **203** | Organization blocks external email verification |
| **400** | Invalid email format or mailbox unavailable |
| **403** | Email or domain is blacklisted |
| **404** | Mail server not found (no MX/A/AAAA) |
| **500** | Internal or SMTP server error |
| **502** | IP blocked by Spamhaus |
| **503** | Network connection error |

## Configuration

Pass a config dict to `verify_email()` or `verify_emails_list()`:

```python
from mailValidator import verify_email

config = {
    "timeout": 10,
    "whitelisted_emails": ["allowed@example.com"],
    "blacklisted_emails": ["blocked@example.com"],
    "whitelisted_domains": ["trusted.com"],
    "blacklisted_domains": ["spam.com"],
    "additional_disposable_domains": ["custom-temp.example"],
    "additional_org_block_patterns": ["custom policy pattern"],
}

result = verify_email("user@example.com", config)
```

### Disposable detection notes

- Domains in the bundled blocklist or `additional_disposable_domains` return **`202` immediately** (no DNS/SMTP).
- Domains **not** in the blocklist are validated normally and may return `200` or `201` even if they are temp-mail providers in the real world.
- Add missing domains via `additional_disposable_domains` or extend `disposable_domains.txt` in source.

## Programmatic usage

```python
from mailValidator import verify_email, verify_emails_list

# Single email
result = verify_email("user@example.com")

# Batch
results = verify_emails_list(
    ["valid@company.com", "invalid@bad.com"],
    config={"timeout": 5},
)
# {'valid@company.com': {'status': '200', 'message': '...'}, ...}
```

## Development

```bash
pip install -e ".[dev]"
pytest -v
```

Build a wheel locally:

```bash
pip install build
python -m build
pip install ./dist/mailvalidator-0.2.7.0-py3-none-any.whl
```

See [test-case.md](test-case.md) for the full test catalog.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

Proprietary — see [LICENSE.txt](LICENSE.txt).

Copyright (c) 2024 Anu T
