temp-email-filter 0.1.1__py3-none-any.whl

email_span_filter/py.typed

@@ -0,0 +1 @@
+

temp_email_filter/__init__.py

@@ -0,0 +1,3 @@
+from .checker import check_email, is_disposable_email
+
+__all__ = ["check_email", "is_disposable_email"]

temp_email_filter/checker.py

@@ -0,0 +1,266 @@
+import logging
+import os
+import re
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional, Tuple, cast
+
+import diskcache
+import dns.resolver
+
+logger = logging.getLogger(__name__)
+
+# Configure DNS timeouts to prevent hanging
+try:
+    dns.resolver.default_resolver.timeout = 2
+    dns.resolver.default_resolver.lifetime = 5
+except (AttributeError, TypeError):
+    # Some environments may not support resolver configuration
+    pass
+
+DEFAULT_CACHE_DIR = Path(os.getenv("TEMP_EMAIL_FILTER_CACHE_DIR", ".email_cache"))
+cache = diskcache.Cache(str(DEFAULT_CACHE_DIR))
+
+KNOWN_NOT_DISPOSABLE_DOMAINS = {
+    "gmail.com",
+    "yahoo.com",
+    "hotmail.com",
+    "outlook.com",
+    "protonmail.com",
+    "aol.com",
+    "icloud.com",
+    "zoho.com",
+    "mail.com",
+    "gmx.com",
+}
+
+DISPOSABLE_DOMAINS = {
+    "tempmail.com",
+    "throwawaymail.com",
+    "10minutemail.com",
+    "guerrillamail.com",
+    "mailinator.com",
+    "sharklasers.com",
+    "meltmail.com",
+    "yopmail.com",
+    "fakeinbox.com",
+    "trashmail.com",
+    "mintemail.com",
+    "maildrop.cc",
+    "getnada.com",
+    "dispostable.com",
+    "spamgourmet.com",
+    "jetable.org",
+    "mailnesia.com",
+    "spamavert.com",
+    "emailondeck.com",
+    "mytemp.email",
+    "tmail.com",
+    "boun.cr",
+    "mailcatch.com",
+    "temp-mail.org",
+    "moakt.com",
+    "dropmail.me",
+    "burnermail.io",
+    "mailinator.net",
+    "trashmail.net",
+    "20minutemail.com",
+    "spambog.com",
+    "fake-mail.net",
+    "emailtemporario.com.br",
+    "fakemailgenerator.com",
+    "getairmail.com",
+    "tempail.com",
+    "anonymbox.com",
+    "luxusmail.org",
+    "eyepaste.com",
+    "instant-email.org",
+    "easytrashmail.com",
+    "dockstones.com",
+}
+
+DISPOSABLE_PATTERNS = (
+    # Only keep the numeric timestamp pattern - remove the + pattern which flags legitimate aliases
+    re.compile(r"^[a-zA-Z0-9]+\.[0-9]{10}@"),
+)
+
+RBL_SERVICES = (
+    "multi.surbl.org",
+    "zen.spamhaus.org",
+    "b.barracudacentral.org",
+    "bl.spamcop.net",
+    "dnsbl.sorbs.net",
+    "dnsbl.httpbl.org",
+)
+
+BLOCKED_MX_RECORDS = {
+    "mx2.den.yt",
+}
+
+EMAIL_RE = re.compile(r"^[^@\s]{1,64}@[^@\s]{1,253}$")
+CACHE_TTL_SECONDS = 60 * 60 * 24
+
+
+@dataclass(frozen=True)
+class EmailCheckResult:
+    email: str
+    is_disposable: bool
+    reason: str
+
+
+def _normalize_email(email: str) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+    normalized = email.strip().lower()
+    if not normalized or len(normalized) > 254 or not EMAIL_RE.match(normalized):
+        return None, None, "Invalid email format"
+
+    local_part, domain = normalized.rsplit("@", 1)
+    if not local_part or not domain or ".." in domain:
+        return None, None, "Invalid email format"
+
+    try:
+        ascii_domain = domain.encode("idna").decode("ascii")
+    except UnicodeError:
+        return None, None, "Invalid email domain"
+
+    return f"{local_part}@{ascii_domain}", ascii_domain, None
+
+
+def is_valid_domain(domain: str) -> Tuple[bool, str]:
+    try:
+        mx_records = dns.resolver.resolve(domain, "MX")
+    except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer, dns.resolver.NoNameservers):
+        return False, "Invalid domain or no MX records"
+    except Exception:
+        logger.exception("Error checking domain MX records")
+        return False, "Error checking domain MX records"
+
+    for mx in mx_records:
+        mx_host = str(mx.exchange).rstrip(".").lower()
+        if mx_host in BLOCKED_MX_RECORDS:
+            return False, f"Blocked MX record: {mx_host}"
+
+    return True, "Valid MX record"
+
+
+def check_rbl_ip(ip: str, rbl: str) -> bool:
+    """Check if IP address is listed in RBL service."""
+    try:
+        # Reverse IP octets for RBL query format
+        reversed_ip = ".".join(reversed(ip.split(".")))
+        query = f"{reversed_ip}.{rbl}"
+        dns.resolver.resolve(query, "A")
+        return True
+    except dns.resolver.NXDOMAIN:
+        return False
+    except Exception:
+        logger.exception("Error checking RBL for IP %s", ip)
+        return False
+
+
+def check_rbl(domain: str) -> Tuple[bool, str]:
+    """Check if domain's MX IPs are listed in any RBL service."""
+    try:
+        # Get MX records first
+        mx_records = dns.resolver.resolve(domain, "MX")
+    except (dns.resolver.NXDOMAIN, dns.resolver.NoAnswer, dns.resolver.NoNameservers):
+        return False, "Cannot resolve MX records for RBL check"
+    except Exception:
+        logger.exception("Error resolving MX records for RBL check")
+        return False, "Error resolving MX records for RBL check"
+
+    # Check each MX record's IP against RBLs
+    for mx in mx_records:
+        mx_host = str(mx.exchange).rstrip(".").lower()
+        
+        try:
+            # Resolve MX hostname to IP
+            a_records = dns.resolver.resolve(mx_host, "A")
+            for a_record in a_records:
+                ip = str(a_record)
+                
+                # Check this IP against all RBL services
+                for rbl in RBL_SERVICES:
+                    if check_rbl_ip(ip, rbl):
+                        return True, f"MX IP {ip} listed in {rbl}"
+                        
+        except Exception:
+            logger.exception("Error resolving MX hostname %s to IP", mx_host)
+            continue
+
+    return False, "Not listed in any RBL"
+
+
+def cache_result(domain: str, is_disposable: bool, reason: str) -> None:
+    try:
+        cache.set(
+            domain,
+            {"is_disposable": is_disposable, "reason": reason},
+            expire=CACHE_TTL_SECONDS,
+        )
+    except Exception:
+        logger.exception("Error caching domain result")
+
+
+def is_disposable_email(email: str) -> Tuple[bool, str]:
+    result = check_email(email)
+    return result.is_disposable, result.reason
+
+
+def check_email(email: str) -> EmailCheckResult:
+    normalized_email, domain, validation_error = _normalize_email(email)
+    if validation_error or not normalized_email or not domain:
+        return EmailCheckResult(
+            email=email,
+            is_disposable=True,
+            reason=validation_error or "Invalid email format",
+        )
+
+    # Check known trusted providers first - skip all other checks
+    if domain in KNOWN_NOT_DISPOSABLE_DOMAINS:
+        return EmailCheckResult(
+            email=normalized_email,
+            is_disposable=False,
+            reason="Known trusted provider",
+        )
+
+    # Check cache after trusted provider check
+    cached_result = cast(Any, cache.get(domain))
+    if cached_result:
+        return EmailCheckResult(
+            email=normalized_email,
+            is_disposable=bool(cached_result["is_disposable"]),
+            reason=str(cached_result["reason"]),
+        )
+
+    # Check if domain has valid MX records and is not using blocked MX hosts
+    is_valid, mx_reason = is_valid_domain(domain)
+    if not is_valid:
+        # Only cache permanent failures, not transient DNS errors
+        if not mx_reason.startswith("Error"):
+            cache_result(domain, True, mx_reason)
+        return EmailCheckResult(normalized_email, True, mx_reason)
+
+    # Check against known disposable domains list
+    if domain in DISPOSABLE_DOMAINS:
+        reason = "Known disposable domain"
+        cache_result(domain, True, reason)
+        return EmailCheckResult(normalized_email, True, reason)
+
+    # Check against disposable patterns
+    for pattern in DISPOSABLE_PATTERNS:
+        if pattern.match(normalized_email):
+            reason = "Matched disposable pattern"
+            cache_result(domain, True, reason)
+            return EmailCheckResult(normalized_email, True, reason)
+
+    # Check against RBLs (now properly checks MX IPs)
+    is_listed, rbl_reason = check_rbl(domain)
+    if is_listed:
+        cache_result(domain, True, rbl_reason)
+        return EmailCheckResult(normalized_email, True, rbl_reason)
+
+    # Domain appears legitimate - cache this result too
+    reason = "Not disposable"
+    cache_result(domain, False, reason)
+    return EmailCheckResult(normalized_email, False, reason)

temp_email_filter-0.1.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: temp-email-filter
+Version: 0.1.1
+Summary: Detect disposable email addresses with domain, MX, pattern, and RBL checks.
+Author: Temp Email Filter contributors
+License-Expression: MIT
+Keywords: email,disposable-email,validation,dns,temporary-email
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: diskcache>=5.6
+Requires-Dist: dnspython>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# Temp Email Filter
+
+Temp Email Filter is a Python package for detecting disposable email addresses. It performs comprehensive checks including known disposable domains, trusted provider validation, email patterns, MX record validation, blocked MX hosts, and DNS-based RBL (Real-time Blackhole List) services.
+
+## Features
+
+- **Trusted provider check**: Immediately validates emails from known legitimate providers (Gmail, Yahoo, etc.)
+- **Disposable domain detection**: Checks against known temporary email services
+- **Pattern analysis**: Identifies suspicious email patterns (excludes legitimate + aliases)  
+- **MX record validation**: Verifies domain has valid mail servers
+- **RBL checking**: Queries reputation databases using proper IP-based lookups
+- **Intelligent caching**: Caches both positive and negative results for performance
+- **DNS timeouts**: Prevents hanging on slow DNS queries
+- **Input validation**: Normalizes and validates email format before processing
+
+## Install
+
+```bash
+pip install temp-email-filter
+```
+
+For local development from a clone:
+
+```bash
+git clone <your-repo-url>
+cd temp_email_filter
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Basic Usage
+
+```python
+from temp_email_filter import check_email
+
+result = check_email("test@gmail.com")
+print(f"Email: {result.email}")
+print(f"Is disposable: {result.is_disposable}")
+print(f"Reason: {result.reason}")
+
+if result.is_disposable:
+    print("This email should be rejected")
+else:
+    print("This email is acceptable")
+```
+
+If you only need the original tuple style:
+
+```python
+from temp_email_filter import is_disposable_email
+
+is_disposable, reason = is_disposable_email("test@gmail.com")
+```
+
+## Django Example
+
+```python
+from django.core.exceptions import ValidationError
+from temp_email_filter import check_email
+
+
+def validate_non_disposable_email(value):
+    result = check_email(value)
+    if result.is_disposable:
+        raise ValidationError(result.reason)
+```
+
+Use the validator in a model or serializer field.
+
+## FastAPI Example
+
+This package does not start a FastAPI server. Add it to your own FastAPI app:
+
+```python
+from fastapi import FastAPI, HTTPException
+from temp_email_filter import check_email
+
+app = FastAPI()
+
+
+@app.get("/email-checker")
+def email_checker(email: str):
+    result = check_email(email)
+    if result.reason.startswith("Invalid email"):
+        raise HTTPException(status_code=400, detail=result.reason)
+
+    return {
+        "email": result.email,
+        "is_disposable": result.is_disposable,
+        "reason": result.reason,
+    }
+```
+
+## Running As A Service
+
+This project is package-only. To run it as a service, install it inside your own Django, FastAPI, Flask, worker, or microservice project and call `check_email()` from your route, form validation, serializer, or background job.
+
+## Configuration
+
+The cache directory defaults to `.email_cache`. Override it with:
+
+```bash
+export TEMP_EMAIL_FILTER_CACHE_DIR=/tmp/temp-email-filter-cache
+```
+
+## Recent Improvements (v0.1.1)
+
+- **Fixed RBL checking**: Now properly queries MX record IPs instead of domains
+- **Improved pattern matching**: Removed false positive for legitimate + aliases (john+work@gmail.com)
+- **Enhanced caching**: Now caches both disposable and legitimate results
+- **Better logic flow**: Trusted providers checked first, bypassing expensive DNS operations
+- **DNS timeouts**: Added configurable timeouts to prevent hanging queries
+- **Transient error handling**: Avoids caching temporary DNS failures
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Publishing
+
+Maintainer release steps are documented in [`docs/PYPI.md`](docs/PYPI.md).
+
+## License
+
+MIT

temp_email_filter-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+email_span_filter/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+temp_email_filter/__init__.py,sha256=QUKIvs46DfihRdYrPFnbxjyVXDHOvRLT5mDKDmWlcpg,103
+temp_email_filter/checker.py,sha256=xf2pxS3zfphGriOuplibQ3haWof02yThBv_Li_RdSGk,8024
+temp_email_filter-0.1.1.dist-info/licenses/LICENSE,sha256=fSuk3AWQxAFoSSLUtbuph4BEuheUj3Nu153argFxBkE,1087
+temp_email_filter-0.1.1.dist-info/METADATA,sha256=-1YaTt5DQWx024CXclF4u44b_hNHs2idjvHHqHsVq34,4599
+temp_email_filter-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+temp_email_filter-0.1.1.dist-info/top_level.txt,sha256=Oc_XlWKwU8BRwfhkDXcmHzthT-HjZRt7WxKPfuIUJmM,36
+temp_email_filter-0.1.1.dist-info/RECORD,,

temp_email_filter-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

temp_email_filter-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temp Email Filter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

temp_email_filter-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+email_span_filter
+temp_email_filter