bouncelayer 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BounceLayer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,73 @@
1
+ Metadata-Version: 2.4
2
+ Name: bouncelayer
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for BounceLayer Email Verification API
5
+ Author-email: BounceLayer <support@bouncelayer.com>
6
+ Project-URL: Homepage, https://bouncelayer.com
7
+ Project-URL: Documentation, https://bouncelayer.com/docs
8
+ Project-URL: Source, https://github.com/BounceLayer/bouncelayer-python
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Python: >=3.8
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Dynamic: license-file
16
+
17
+ # bouncelayer (Python SDK)
18
+
19
+ Official Python library for [BounceLayer](https://bouncelayer.com) — real-time email verification with direct TCP port 25 SMTP handshakes.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pip install bouncelayer
25
+ ```
26
+
27
+ ## Quickstart
28
+
29
+ ```python
30
+ from bouncelayer import BounceLayer
31
+ import os
32
+
33
+ client = BounceLayer(api_key=os.environ.get("BOUNCELAYER_API_KEY"))
34
+
35
+ # Single real-time verification (<150ms)
36
+ result = client.verify.single("alex@stripe.com")
37
+
38
+ print(result.status) # "valid"
39
+ print(result.confidence_score) # 98
40
+ print(result.is_disposable) # False
41
+ print(result.smtp_checked) # True
42
+ ```
43
+
44
+ ## Bulk Verification
45
+
46
+ ```python
47
+ # Submit a list of up to 10,000 addresses
48
+ job = client.verify.bulk([
49
+ "sarah@linear.app",
50
+ "john@workmail.com",
51
+ "disposable@burner.org"
52
+ ], webhook_url="https://api.myapp.com/webhooks/bouncelayer")
53
+
54
+ # Wait for job completion automatically
55
+ completed = client.verify.wait_for_job(job["job_id"])
56
+ print(f"Valid: {completed.valid_count}, Invalid: {completed.invalid_count}")
57
+ ```
58
+
59
+ ## Webhook Verification (Flask / FastAPI)
60
+
61
+ ```python
62
+ from bouncelayer import BounceLayer
63
+
64
+ # In your webhook route
65
+ is_valid = BounceLayer.verify_webhook_signature(
66
+ raw_body_bytes,
67
+ request.headers.get("X-BounceLayer-Signature"),
68
+ secret="whsec_..."
69
+ )
70
+ ```
71
+
72
+ ## License
73
+ MIT
@@ -0,0 +1,57 @@
1
+ # bouncelayer (Python SDK)
2
+
3
+ Official Python library for [BounceLayer](https://bouncelayer.com) — real-time email verification with direct TCP port 25 SMTP handshakes.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install bouncelayer
9
+ ```
10
+
11
+ ## Quickstart
12
+
13
+ ```python
14
+ from bouncelayer import BounceLayer
15
+ import os
16
+
17
+ client = BounceLayer(api_key=os.environ.get("BOUNCELAYER_API_KEY"))
18
+
19
+ # Single real-time verification (<150ms)
20
+ result = client.verify.single("alex@stripe.com")
21
+
22
+ print(result.status) # "valid"
23
+ print(result.confidence_score) # 98
24
+ print(result.is_disposable) # False
25
+ print(result.smtp_checked) # True
26
+ ```
27
+
28
+ ## Bulk Verification
29
+
30
+ ```python
31
+ # Submit a list of up to 10,000 addresses
32
+ job = client.verify.bulk([
33
+ "sarah@linear.app",
34
+ "john@workmail.com",
35
+ "disposable@burner.org"
36
+ ], webhook_url="https://api.myapp.com/webhooks/bouncelayer")
37
+
38
+ # Wait for job completion automatically
39
+ completed = client.verify.wait_for_job(job["job_id"])
40
+ print(f"Valid: {completed.valid_count}, Invalid: {completed.invalid_count}")
41
+ ```
42
+
43
+ ## Webhook Verification (Flask / FastAPI)
44
+
45
+ ```python
46
+ from bouncelayer import BounceLayer
47
+
48
+ # In your webhook route
49
+ is_valid = BounceLayer.verify_webhook_signature(
50
+ raw_body_bytes,
51
+ request.headers.get("X-BounceLayer-Signature"),
52
+ secret="whsec_..."
53
+ )
54
+ ```
55
+
56
+ ## License
57
+ MIT
@@ -0,0 +1,15 @@
1
+ from .client import BounceLayer
2
+ from .exceptions import BounceLayerError, AuthenticationError, InsufficientCreditsError, RateLimitError
3
+ from .models import VerificationResult, BulkJobStatus
4
+
5
+ __all__ = [
6
+ "BounceLayer",
7
+ "BounceLayerError",
8
+ "AuthenticationError",
9
+ "InsufficientCreditsError",
10
+ "RateLimitError",
11
+ "VerificationResult",
12
+ "BulkJobStatus",
13
+ ]
14
+
15
+ __version__ = "1.0.0"
@@ -0,0 +1,167 @@
1
+ import os
2
+ import time
3
+ import hmac
4
+ import hashlib
5
+ import json
6
+ from typing import List, Optional, Dict, Any, Union
7
+ import urllib.request
8
+ import urllib.error
9
+
10
+ from .exceptions import (
11
+ BounceLayerError,
12
+ AuthenticationError,
13
+ InsufficientCreditsError,
14
+ RateLimitError,
15
+ )
16
+ from .models import VerificationResult, BulkJobStatus
17
+
18
+
19
+ class BounceLayer:
20
+ """Official Python Client for BounceLayer API."""
21
+
22
+ def __init__(
23
+ self,
24
+ api_key: Optional[str] = None,
25
+ base_url: str = "https://api.bouncelayer.com/v1",
26
+ timeout: int = 30,
27
+ ):
28
+ self.api_key = api_key or os.environ.get("BOUNCELAYER_API_KEY")
29
+ if not self.api_key:
30
+ raise AuthenticationError(
31
+ "Missing BounceLayer API key. Pass BounceLayer(api_key='bl_live_...') "
32
+ "or set BOUNCELAYER_API_KEY environment variable."
33
+ )
34
+ self.base_url = base_url.rstrip("/")
35
+ self.timeout = timeout
36
+
37
+ def _request(
38
+ self,
39
+ method: str,
40
+ path: str,
41
+ data: Optional[dict] = None,
42
+ params: Optional[dict] = None,
43
+ ) -> dict:
44
+ url = f"{self.base_url}{path if path.startswith('/') else '/' + path}"
45
+ if params:
46
+ query = urllib.parse.urlencode(params)
47
+ url = f"{url}?{query}"
48
+
49
+ headers = {
50
+ "X-API-Key": self.api_key,
51
+ "Content-Type": "application/json",
52
+ "User-Agent": "BounceLayer-Python-SDK/1.0.0",
53
+ }
54
+
55
+ body = json.dumps(data).encode("utf-8") if data is not None else None
56
+ req = urllib.request.Request(url, data=body, headers=headers, method=method)
57
+
58
+ try:
59
+ with urllib.request.urlopen(req, timeout=self.timeout) as response:
60
+ return json.loads(response.read().decode("utf-8"))
61
+ except urllib.error.HTTPError as err:
62
+ err_body = err.read().decode("utf-8")
63
+ try:
64
+ err_json = json.loads(err_body)
65
+ except Exception:
66
+ err_json = {"detail": err_body or err.reason}
67
+
68
+ msg = err_json.get("detail") or err_json.get("message") or str(err)
69
+
70
+ if err.code == 401:
71
+ raise AuthenticationError(msg, err.code, err_json)
72
+ elif err.code == 402:
73
+ raise InsufficientCreditsError(msg, err.code, err_json)
74
+ elif err.code == 429:
75
+ raise RateLimitError(msg, err.code, err_json)
76
+ else:
77
+ raise BounceLayerError(msg, err.code, err_json)
78
+ except Exception as e:
79
+ raise BounceLayerError(f"Request failed: {str(e)}")
80
+
81
+ class _Verify:
82
+ def __init__(self, client: "BounceLayer"):
83
+ self._client = client
84
+
85
+ def single(self, email: str) -> VerificationResult:
86
+ """Verify a single email address in real-time across 7 layers."""
87
+ res = self._client._request(
88
+ "POST", "/verify/single", data={"email": email.strip().lower()}
89
+ )
90
+ return VerificationResult.from_dict(res.get("result", {}))
91
+
92
+ def bulk(
93
+ self, emails: List[str], webhook_url: Optional[str] = None
94
+ ) -> dict:
95
+ """Submit a list of up to 10,000 email addresses for async bulk verification."""
96
+ payload = {"emails": emails}
97
+ if webhook_url:
98
+ payload["webhook_url"] = webhook_url
99
+ return self._client._request("POST", "/verify/bulk", data=payload)
100
+
101
+ def get_job(self, job_id: str) -> BulkJobStatus:
102
+ """Fetch status and results of a bulk verification job."""
103
+ res = self._client._request("GET", f"/verify/bulk/{job_id}")
104
+ return BulkJobStatus.from_dict(res)
105
+
106
+ def wait_for_job(
107
+ self,
108
+ job_id: str,
109
+ interval: float = 2.0,
110
+ max_wait: float = 120.0,
111
+ ) -> BulkJobStatus:
112
+ """Poll until a bulk job is completed or cancelled."""
113
+ start_time = time.time()
114
+ while time.time() - start_time < max_wait:
115
+ job = self.get_job(job_id)
116
+ if job.status in ("completed", "cancelled", "failed"):
117
+ return job
118
+ time.sleep(interval)
119
+ raise BounceLayerError(f"Job {job_id} timed out after {max_wait}s")
120
+
121
+ def cancel_job(self, job_id: str) -> dict:
122
+ """Cancel a pending bulk job and release reserved credits."""
123
+ return self._client._request("DELETE", f"/verify/bulk/{job_id}")
124
+
125
+ class _Credits:
126
+ def __init__(self, client: "BounceLayer"):
127
+ self._client = client
128
+
129
+ def get(self) -> dict:
130
+ """Return current credit balance and account telemetry."""
131
+ return self._client._request("GET", "/credits")
132
+
133
+ class _Intelligence:
134
+ def __init__(self, client: "BounceLayer"):
135
+ self._client = client
136
+
137
+ def analyze_risk(self, email_or_domain: str) -> dict:
138
+ """Analyze threat and disposable domain risk signals."""
139
+ key = "email" if "@" in email_or_domain else "domain"
140
+ return self._client._request("GET", f"/intelligence/risk?{key}={email_or_domain}")
141
+
142
+ @property
143
+ def verify(self) -> _Verify:
144
+ return self._Verify(self)
145
+
146
+ @property
147
+ def credits(self) -> _Credits:
148
+ return self._Credits(self)
149
+
150
+ @property
151
+ def intelligence(self) -> _Intelligence:
152
+ return self._Intelligence(self)
153
+
154
+ @staticmethod
155
+ def verify_webhook_signature(
156
+ payload: Union[str, bytes], signature_header: str, secret: str
157
+ ) -> bool:
158
+ """Verify HMAC-SHA256 signature from BounceLayer webhooks."""
159
+ if not payload or not signature_header or not secret:
160
+ return False
161
+ try:
162
+ body = payload.encode("utf-8") if isinstance(payload, str) else payload
163
+ expected = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
164
+ given = signature_header.replace("sha256=", "").strip()
165
+ return hmac.compare_digest(expected, given)
166
+ except Exception:
167
+ return False
@@ -0,0 +1,21 @@
1
+ class BounceLayerError(Exception):
2
+ """Base exception for all BounceLayer SDK errors."""
3
+ def __init__(self, message: str, status_code: int = None, details: dict = None):
4
+ super().__init__(message)
5
+ self.status_code = status_code
6
+ self.details = details or {}
7
+
8
+
9
+ class AuthenticationError(BounceLayerError):
10
+ """Raised when the API key is missing or invalid."""
11
+ pass
12
+
13
+
14
+ class InsufficientCreditsError(BounceLayerError):
15
+ """Raised when the account balance has 0 credits."""
16
+ pass
17
+
18
+
19
+ class RateLimitError(BounceLayerError):
20
+ """Raised when API rate limits are exceeded."""
21
+ pass
@@ -0,0 +1,84 @@
1
+ from dataclasses import dataclass
2
+ from typing import List, Optional, Any, Dict
3
+
4
+
5
+ @dataclass
6
+ class MXRecord:
7
+ priority: int
8
+ host: str = ""
9
+
10
+
11
+ @dataclass
12
+ class VerificationResult:
13
+ email: str
14
+ status: str
15
+ is_valid: bool
16
+ syntax_valid: bool
17
+ domain: str
18
+ domain_valid: bool
19
+ has_mx: bool
20
+ is_disposable: bool
21
+ is_role_based: bool
22
+ is_catch_all: bool
23
+ is_free_provider: bool
24
+ confidence_score: int
25
+ status_reason: str
26
+ provider: str
27
+ verification_time_ms: int
28
+ cached: bool
29
+ smtp_checked: bool = True
30
+ smtp_response_code: Optional[int] = None
31
+ mx_records: Optional[List[Dict[str, Any]]] = None
32
+
33
+ @classmethod
34
+ def from_dict(cls, data: dict) -> "VerificationResult":
35
+ return cls(
36
+ email=data.get("email", ""),
37
+ status=data.get("status", "unknown"),
38
+ is_valid=data.get("is_valid", False),
39
+ syntax_valid=data.get("syntax_valid", False),
40
+ domain=data.get("domain", ""),
41
+ domain_valid=data.get("domain_valid", False),
42
+ has_mx=data.get("has_mx", False),
43
+ is_disposable=data.get("is_disposable", False),
44
+ is_role_based=data.get("is_role_based", False),
45
+ is_catch_all=data.get("is_catch_all", False),
46
+ is_free_provider=data.get("is_free_provider", False),
47
+ confidence_score=data.get("confidence_score", 0),
48
+ status_reason=data.get("status_reason", ""),
49
+ provider=data.get("provider", "unknown"),
50
+ verification_time_ms=data.get("verification_time_ms", 0),
51
+ cached=data.get("cached", False),
52
+ smtp_checked=data.get("smtp_checked", True),
53
+ smtp_response_code=data.get("smtp_response_code"),
54
+ mx_records=data.get("mx_records"),
55
+ )
56
+
57
+
58
+ @dataclass
59
+ class BulkJobStatus:
60
+ job_id: str
61
+ status: str
62
+ total_emails: int
63
+ processed_emails: int
64
+ valid_count: int
65
+ invalid_count: int
66
+ credits_used: int
67
+ created_at: str
68
+ completed_at: Optional[str] = None
69
+ results: Optional[List[dict]] = None
70
+
71
+ @classmethod
72
+ def from_dict(cls, data: dict) -> "BulkJobStatus":
73
+ return cls(
74
+ job_id=data.get("job_id", ""),
75
+ status=data.get("status", "pending"),
76
+ total_emails=data.get("total_emails", 0),
77
+ processed_emails=data.get("processed_emails", 0),
78
+ valid_count=data.get("valid_count", 0),
79
+ invalid_count=data.get("invalid_count", 0),
80
+ credits_used=data.get("credits_used", 0),
81
+ created_at=data.get("created_at", ""),
82
+ completed_at=data.get("completed_at"),
83
+ results=data.get("results"),
84
+ )
@@ -0,0 +1,73 @@
1
+ Metadata-Version: 2.4
2
+ Name: bouncelayer
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for BounceLayer Email Verification API
5
+ Author-email: BounceLayer <support@bouncelayer.com>
6
+ Project-URL: Homepage, https://bouncelayer.com
7
+ Project-URL: Documentation, https://bouncelayer.com/docs
8
+ Project-URL: Source, https://github.com/BounceLayer/bouncelayer-python
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Python: >=3.8
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Dynamic: license-file
16
+
17
+ # bouncelayer (Python SDK)
18
+
19
+ Official Python library for [BounceLayer](https://bouncelayer.com) — real-time email verification with direct TCP port 25 SMTP handshakes.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pip install bouncelayer
25
+ ```
26
+
27
+ ## Quickstart
28
+
29
+ ```python
30
+ from bouncelayer import BounceLayer
31
+ import os
32
+
33
+ client = BounceLayer(api_key=os.environ.get("BOUNCELAYER_API_KEY"))
34
+
35
+ # Single real-time verification (<150ms)
36
+ result = client.verify.single("alex@stripe.com")
37
+
38
+ print(result.status) # "valid"
39
+ print(result.confidence_score) # 98
40
+ print(result.is_disposable) # False
41
+ print(result.smtp_checked) # True
42
+ ```
43
+
44
+ ## Bulk Verification
45
+
46
+ ```python
47
+ # Submit a list of up to 10,000 addresses
48
+ job = client.verify.bulk([
49
+ "sarah@linear.app",
50
+ "john@workmail.com",
51
+ "disposable@burner.org"
52
+ ], webhook_url="https://api.myapp.com/webhooks/bouncelayer")
53
+
54
+ # Wait for job completion automatically
55
+ completed = client.verify.wait_for_job(job["job_id"])
56
+ print(f"Valid: {completed.valid_count}, Invalid: {completed.invalid_count}")
57
+ ```
58
+
59
+ ## Webhook Verification (Flask / FastAPI)
60
+
61
+ ```python
62
+ from bouncelayer import BounceLayer
63
+
64
+ # In your webhook route
65
+ is_valid = BounceLayer.verify_webhook_signature(
66
+ raw_body_bytes,
67
+ request.headers.get("X-BounceLayer-Signature"),
68
+ secret="whsec_..."
69
+ )
70
+ ```
71
+
72
+ ## License
73
+ MIT
@@ -0,0 +1,11 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ bouncelayer/__init__.py
5
+ bouncelayer/client.py
6
+ bouncelayer/exceptions.py
7
+ bouncelayer/models.py
8
+ bouncelayer.egg-info/PKG-INFO
9
+ bouncelayer.egg-info/SOURCES.txt
10
+ bouncelayer.egg-info/dependency_links.txt
11
+ bouncelayer.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ bouncelayer
@@ -0,0 +1,23 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "bouncelayer"
7
+ version = "1.0.0"
8
+ authors = [
9
+ { name="BounceLayer", email="support@bouncelayer.com" },
10
+ ]
11
+ description = "Official Python SDK for BounceLayer Email Verification API"
12
+ readme = "README.md"
13
+ requires-python = ">=3.8"
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Operating System :: OS Independent",
18
+ ]
19
+
20
+ [project.urls]
21
+ "Homepage" = "https://bouncelayer.com"
22
+ "Documentation" = "https://bouncelayer.com/docs"
23
+ "Source" = "https://github.com/BounceLayer/bouncelayer-python"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+