Metadata-Version: 2.4
Name: identify_fake_email
Version: 1.0.3
Summary: FastAPI
Home-page: 
Author: OpenAPI Generator community
Author-email: OpenAPI Generator Community <team@openapitools.org>
Project-URL: Repository, https://github.com/GIT_USER_ID/GIT_REPO_ID
Keywords: OpenAPI,OpenAPI-Generator,FastAPI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author

# identify-fake-email

A Python SDK for the [Email Validator API](https://rapidapi.com/JP1V/api/email-validator-syntax-mx-disposable-risk-detection) — ML-powered email validation that goes beyond blacklists.

Most validators rely on MX records, SMTP checks, or static blacklists. This API combines traditional checks with an XGBoost model that scores the risk of accepting an email based on patterns in the username and domain — catching auto-generated disposable emails that traditional methods miss.

## Installation

```bash
pip install identify-fake-email
```

## Requirements

- Python 3.7+
- A [RapidAPI](https://rapidapi.com/JP1V/api/email-validator-syntax-mx-disposable-risk-detection) key (free tier available — 100 requests/month)

## Quick Start

```python
import identify_fake_email
from identify_fake_email.api.default_api import DefaultApi
from identify_fake_email.configuration import Configuration

config = Configuration()
config.api_key["x-rapidapi-key"] = "YOUR_RAPIDAPI_KEY"

client = DefaultApi(identify_fake_email.ApiClient(config))

result = client.validate_email_validate_get("user@example.com")

print(f"Valid: {result.valid_email}")
print(f"Name risk: {result.name_risk}")

if result.valid_email and result.name_risk < 0.7:
    print("Safe to accept")
else:
    print("Suspicious - review")
```

## Bulk Validation

Validate up to 30 emails per request.

```python
from identify_fake_email.models.bulk_emails import BulkEmails

bulk = BulkEmails(emails=["user1@example.com", "user2@example.com"])
results = client.validate_bulk_validate_bulk_post(bulk)

for result in results:
    print(f"{result.email}: name_risk={result.name_risk}")
    if result.valid_email and result.name_risk < 0.7:
        print("Safe to accept")
    else:
        print("Suspicious - review")
```

## Response Fields

| Field | Type | Description |
|---|---|---|
| `email` | string | The email address validated |
| `valid_email_structure` | bool | Whether the email has valid syntax |
| `is_role` | bool | Whether it's a role address (e.g. admin@, support@) |
| `mx_records` | bool | Whether the domain has valid MX records |
| `not_disposable` | bool | Whether the domain is on the disposable blacklist |
| `new_domain` | bool | Whether the domain was recently created |
| `name_risk` | float (0–1) | ML risk score for the username — higher means riskier |
| `domain_risk` | float (0–1) | ML risk score for the domain — higher means riskier |
| `valid_email` | bool | Overall validity based on traditional checks |

## Risk Scores

`name_risk` and `domain_risk` are ML-generated scores between 0 and 1. The higher the score, the more likely the email is fake or disposable.

`name_risk` is the more reliable of the two — auto-generated usernames follow distinct patterns (random characters, high digit count, unusual consonant/vowel ratios) that the model picks up on. `domain_risk` is less reliable as auto-generated domains can look similar to legitimate ones.

**We recommend using `name_risk` as your primary signal** and combining it with other fields for the most accurate result. The threshold is up to you — 0.7 is a reasonable starting point but you can adjust it for your use case.

## Notes

- SMTP validation is intentionally excluded — disposable emails have real mailboxes so SMTP returns valid, adding latency with no benefit
- Bulk validation supports up to 30 emails per request
- The SDK is auto-generated from the [OpenAPI spec](https://jp1v.github.io/email-validator-openapi/)

## Links

- [RapidAPI Listing](https://rapidapi.com/JP1V/api/email-validator-syntax-mx-disposable-risk-detection) — subscribe and get your API key
- [Interactive Swagger Docs](https://jp1v.github.io/email-validator-openapi/) — explore all endpoints and parameters
- [OpenAPI Spec](https://github.com/JP1V/email-validator-openapi) — source spec and SDK generation workflow

## License

MIT
