Metadata-Version: 2.4
Name: is-burner-email
Version: 1.3.6
Summary: Fast, offline burner / disposable email detection with three-list (blacklist/whitelist/graylist) classification.
Project-URL: Homepage, https://github.com/kristijandraca/is-burner-email
Project-URL: Repository, https://github.com/kristijandraca/is-burner-email
Project-URL: Issues, https://github.com/kristijandraca/is-burner-email/issues
Author: kristijandraca
License: MIT
Keywords: burner,disposable,email,offline,temporary,validator
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# is-burner-email (Python)

Fast, offline detection of burner / disposable emails.

- **Offline.** Domain lists bundled inside the wheel. No network calls at runtime.
- **Zero runtime dependencies.**
- **Three lists.** `blacklist` (burners), `whitelist` (always allowed), `graylist` (email alias / forwarding services — blocked only in strict mode).
- **Typed** (ships `py.typed`). Python 3.9+.

## Install

```sh
pip install is-burner-email
```

## Usage

```python
from is_burner_email import is_burner, check

is_burner("user@mailinator.com")                # True
is_burner("user@gmail.com")                     # False
is_burner("user@duck.com")                      # False (normal mode)
is_burner("user@duck.com", mode="strict")       # True

check("user@duck.com", mode="strict")
# {
#   'burner': True,
#   'domain': 'duck.com',
#   'list': 'graylist',
#   'reason': 'graylisted-strict'
# }
```

### Runtime overrides

```python
from is_burner_email import add_to_blacklist, add_to_whitelist

add_to_blacklist("badactor.example")
add_to_whitelist("our-corporate-domain.example")
```

Whitelist always wins over blacklist.

## CLI

```sh
burner user@mailinator.com
# BURNER (blacklist): mailinator.com [blacklisted]

burner user@duck.com --strict --json
# {"burner": true, "domain": "duck.com", "list": "graylist", "reason": "graylisted-strict", "mode": "strict"}

burner --stats
```

Exit codes: `0` clean, `1` burner, `2` invalid input.

## License

MIT
