byebouncer 0.1.0__tar.gz

byebouncer-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Binaries
+/bin/
+/dist/
+/server
+server.exe
+*.exe
+*.dll
+*.so
+*.dylib
+
+# Test binaries
+*.test
+*.out
+
+# Go
+vendor/
+coverage.out
+coverage.html
+
+# Env / secrets
+.env
+.env.local
+.env.*.local
+.env.example
+*.pem
+*.key
+
+# IDE
+.claude/
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Node / Next.js (web/)
+web/node_modules/
+sdks/node/node_modules/
+sdks/node/dist/
+sdks/node/dist-cjs/
+web/.next/
+web/out/
+web/.turbo/
+web/.vercel/
+
+# Logs
+*.log
+logs/
+
+# Data files that are downloaded at build/run time
+data/disposable_domains_downloaded.txt
+sdks/python/.venv/
+sdks/python/**/__pycache__/
+sdks/python/**/*.egg-info/
+sdks/python/.pytest_cache/
+sdks/python/dist/

byebouncer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ByeBouncer
+
+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.

byebouncer-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: byebouncer
+Version: 0.1.0
+Summary: Official Python SDK for the ByeBouncer email verification API.
+Project-URL: Homepage, https://byebouncer.com
+Project-URL: Documentation, https://byebouncer.com/docs
+Project-URL: Repository, https://github.com/fidelp27/byebouncer
+Project-URL: Issues, https://github.com/fidelp27/byebouncer/issues
+Author-email: ByeBouncer <hello@byebouncer.com>
+License: MIT License
+        
+        Copyright (c) 2026 ByeBouncer
+        
+        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.
+License-File: LICENSE
+Keywords: bounce,email,email-validation,smtp,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# byebouncer
+
+Official Python SDK for the [ByeBouncer](https://byebouncer.com) email verification API.
+
+Sync and async clients, real-time single-email verification, bulk CSV verification (up to 50k emails per job), HMAC-signed webhooks.
+
+## Install
+
+```bash
+pip install byebouncer
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from byebouncer import ByeBouncer
+
+with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+    result = client.verify("user@gmail.com")
+    print(result.status)             # "deliverable" | "undeliverable" | "risky" | "unknown"
+    print(result.action)             # "allow" | "review" | "block"
+    print(result.signals)            # ["valid_syntax", "mx_found", ...]
+    print(result.credits_remaining)
+```
+
+Get your `BB_API_KEY` from https://byebouncer.com/dashboard (format `bb_live_...`).
+
+## Async
+
+```python
+import asyncio
+from byebouncer import AsyncByeBouncer
+
+async def main():
+    async with AsyncByeBouncer(api_key="bb_live_...") as client:
+        result = await client.verify("user@gmail.com")
+        print(result.status)
+
+asyncio.run(main())
+```
+
+## Bulk verification
+
+```python
+created = client.bulk(
+    emails=["a@gmail.com", "b@outlook.com"],  # up to 50.000
+    filename="my_list.csv",
+    webhook_url="https://api.myapp.com/hooks/byebouncer",  # optional
+)
+job = created.job
+print(f"Job {job.id}, {job.total_emails} emails")
+print(f"Estimated duration: {created.estimated_seconds}s")
+
+# Present when webhook_url is supplied (generated or supplied).
+# Store it now: it is never returned by later job reads.
+webhook_secret = created.webhook_secret
+```
+
+### Polling for completion
+
+```python
+final = client.bulk_wait_for_completion(
+    job.id,
+    interval_seconds=3,
+    on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
+)
+
+if final.status == "completed":
+    download = client.bulk_download_url(final.id)
+    csv = httpx.get(download.url).text
+    open("results.csv", "w").write(csv)
+```
+
+### Webhooks (recommended for large jobs)
+
+Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:
+
+```
+X-ByeBouncer-Event: bulk.completed
+X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
+```
+
+Attach or rotate the webhook after creating the job:
+
+```python
+result = client.bulk_set_webhook(
+    job.id,
+    webhook_url="https://api.myapp.com/hooks/byebouncer",
+)
+webhook_secret = result.webhook_secret  # store it NOW, returned only once
+```
+
+### Cancel
+
+```python
+cancelled = client.bulk_cancel(job.id)
+print(f"Refunded {cancelled.credits_refunded} credits")
+```
+
+## Error handling
+
+Non-2xx responses raise `ByeBouncerError` or a subclass with `code`, `status`, `detail`.
+
+```python
+from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer
+
+with ByeBouncer(api_key="bb_live_...") as client:
+    try:
+        client.verify("user@gmail.com")
+    except InsufficientCreditsError as e:
+        print(f"Out of credits (remaining: {e.credits_remaining})")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after_seconds}s")
+```
+
+## API reference
+
+Every method mirrors the [OpenAPI spec](https://github.com/fidelp27/byebouncer/blob/master/docs/api/openapi.yaml).
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `verify(email)` | `POST /verify` | Verify a single email |
+| `credits()` | `GET /credits` | Get balance |
+| `bulk(emails, ...)` | `POST /bulk` | Enqueue a bulk job |
+| `bulk_status(job_id)` | `GET /bulk/{id}` | Fetch job |
+| `bulk_cancel(job_id)` | `DELETE /bulk/{id}` | Cancel |
+| `bulk_download_url(job_id)` | `GET /bulk/{id}/download` | Signed CSV URL |
+| `bulk_set_webhook(job_id, ...)` | `POST /bulk/{id}/webhook` | Attach/rotate webhook |
+| `bulk_wait_for_completion(job_id, ...)` | polls | Convenience helper |
+| `bulk_and_wait(emails, ...)` | create+poll+download | Available in sync and async clients |
+
+## Support
+
+- Docs: https://byebouncer.com/docs
+- Email: hello@byebouncer.com
+- Issues: https://github.com/fidelp27/byebouncer/issues
+
+## License
+
+MIT © ByeBouncer

byebouncer-0.1.0/README.md

@@ -0,0 +1,143 @@
+# byebouncer
+
+Official Python SDK for the [ByeBouncer](https://byebouncer.com) email verification API.
+
+Sync and async clients, real-time single-email verification, bulk CSV verification (up to 50k emails per job), HMAC-signed webhooks.
+
+## Install
+
+```bash
+pip install byebouncer
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import os
+from byebouncer import ByeBouncer
+
+with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+    result = client.verify("user@gmail.com")
+    print(result.status)             # "deliverable" | "undeliverable" | "risky" | "unknown"
+    print(result.action)             # "allow" | "review" | "block"
+    print(result.signals)            # ["valid_syntax", "mx_found", ...]
+    print(result.credits_remaining)
+```
+
+Get your `BB_API_KEY` from https://byebouncer.com/dashboard (format `bb_live_...`).
+
+## Async
+
+```python
+import asyncio
+from byebouncer import AsyncByeBouncer
+
+async def main():
+    async with AsyncByeBouncer(api_key="bb_live_...") as client:
+        result = await client.verify("user@gmail.com")
+        print(result.status)
+
+asyncio.run(main())
+```
+
+## Bulk verification
+
+```python
+created = client.bulk(
+    emails=["a@gmail.com", "b@outlook.com"],  # up to 50.000
+    filename="my_list.csv",
+    webhook_url="https://api.myapp.com/hooks/byebouncer",  # optional
+)
+job = created.job
+print(f"Job {job.id}, {job.total_emails} emails")
+print(f"Estimated duration: {created.estimated_seconds}s")
+
+# Present when webhook_url is supplied (generated or supplied).
+# Store it now: it is never returned by later job reads.
+webhook_secret = created.webhook_secret
+```
+
+### Polling for completion
+
+```python
+final = client.bulk_wait_for_completion(
+    job.id,
+    interval_seconds=3,
+    on_progress=lambda j: print(f"{j.processed}/{j.total_emails}"),
+)
+
+if final.status == "completed":
+    download = client.bulk_download_url(final.id)
+    csv = httpx.get(download.url).text
+    open("results.csv", "w").write(csv)
+```
+
+### Webhooks (recommended for large jobs)
+
+Prefer webhooks over polling. On completion ByeBouncer POSTs to your URL with:
+
+```
+X-ByeBouncer-Event: bulk.completed
+X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>
+```
+
+Attach or rotate the webhook after creating the job:
+
+```python
+result = client.bulk_set_webhook(
+    job.id,
+    webhook_url="https://api.myapp.com/hooks/byebouncer",
+)
+webhook_secret = result.webhook_secret  # store it NOW, returned only once
+```
+
+### Cancel
+
+```python
+cancelled = client.bulk_cancel(job.id)
+print(f"Refunded {cancelled.credits_refunded} credits")
+```
+
+## Error handling
+
+Non-2xx responses raise `ByeBouncerError` or a subclass with `code`, `status`, `detail`.
+
+```python
+from byebouncer import InsufficientCreditsError, RateLimitError, ByeBouncer
+
+with ByeBouncer(api_key="bb_live_...") as client:
+    try:
+        client.verify("user@gmail.com")
+    except InsufficientCreditsError as e:
+        print(f"Out of credits (remaining: {e.credits_remaining})")
+    except RateLimitError as e:
+        print(f"Rate limited, retry after {e.retry_after_seconds}s")
+```
+
+## API reference
+
+Every method mirrors the [OpenAPI spec](https://github.com/fidelp27/byebouncer/blob/master/docs/api/openapi.yaml).
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `verify(email)` | `POST /verify` | Verify a single email |
+| `credits()` | `GET /credits` | Get balance |
+| `bulk(emails, ...)` | `POST /bulk` | Enqueue a bulk job |
+| `bulk_status(job_id)` | `GET /bulk/{id}` | Fetch job |
+| `bulk_cancel(job_id)` | `DELETE /bulk/{id}` | Cancel |
+| `bulk_download_url(job_id)` | `GET /bulk/{id}/download` | Signed CSV URL |
+| `bulk_set_webhook(job_id, ...)` | `POST /bulk/{id}/webhook` | Attach/rotate webhook |
+| `bulk_wait_for_completion(job_id, ...)` | polls | Convenience helper |
+| `bulk_and_wait(emails, ...)` | create+poll+download | Available in sync and async clients |
+
+## Support
+
+- Docs: https://byebouncer.com/docs
+- Email: hello@byebouncer.com
+- Issues: https://github.com/fidelp27/byebouncer/issues
+
+## License
+
+MIT © ByeBouncer

byebouncer-0.1.0/byebouncer/__init__.py

@@ -0,0 +1,38 @@
+"""Official Python SDK for the ByeBouncer email verification API."""
+
+from .client import AsyncByeBouncer, ByeBouncer
+from .errors import (
+    ByeBouncerError,
+    InsufficientCreditsError,
+    RateLimitError,
+    UnauthorizedError,
+)
+from .models import (
+    BulkJob,
+    BulkJobStatus,
+    CreateBulkResponse,
+    CreditsInfo,
+    DomainInfo,
+    DownloadResponse,
+    SetWebhookResponse,
+    VerifyResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncByeBouncer",
+    "BulkJob",
+    "BulkJobStatus",
+    "ByeBouncer",
+    "ByeBouncerError",
+    "CreateBulkResponse",
+    "CreditsInfo",
+    "DomainInfo",
+    "DownloadResponse",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "SetWebhookResponse",
+    "UnauthorizedError",
+    "VerifyResult",
+]

byebouncer-0.1.0/byebouncer/client.py

@@ -0,0 +1,371 @@
+"""Sync and async clients for the ByeBouncer API.
+
+Same surface as the Node SDK. `ByeBouncer` is sync, `AsyncByeBouncer` is async;
+they share `_request` semantics and error translation via helpers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from json import JSONDecodeError
+from typing import Any, Callable, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .errors import (
+    ByeBouncerError,
+    InsufficientCreditsError,
+    RateLimitError,
+    UnauthorizedError,
+)
+from .models import (
+    TERMINAL_STATUSES,
+    BulkJob,
+    CreateBulkResponse,
+    CreditsInfo,
+    DownloadResponse,
+    SetWebhookResponse,
+    VerifyResult,
+)
+
+DEFAULT_BASE_URL = "https://api.byebouncer.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "byebouncer-python/0.1.0"
+
+
+def _parse_error(response: httpx.Response) -> ByeBouncerError:
+    payload: dict[str, Any] = {}
+    try:
+        payload = response.json()
+    except (JSONDecodeError, ValueError):
+        payload = {}
+    code = payload.get("error") or f"http_{response.status_code}"
+    detail = payload.get("detail")
+    status = response.status_code
+    if status == 401:
+        return UnauthorizedError(detail=detail, response=payload)
+    if status == 402:
+        return InsufficientCreditsError(
+            detail=detail,
+            response=payload,
+            credits_remaining=payload.get("credits_remaining"),
+        )
+    if status == 429:
+        ra = response.headers.get("retry-after")
+        return RateLimitError(
+            detail=detail,
+            response=payload,
+            retry_after_seconds=int(ra) if ra and ra.isdigit() else None,
+        )
+    return ByeBouncerError(code=code, status=status, detail=detail, response=payload)
+
+
+class ByeBouncer:
+    """Synchronous client. For high-throughput usage prefer `AsyncByeBouncer`."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "ByeBouncer":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ─── Endpoints ────────────────────────────────────────────
+
+    def verify(self, email: str) -> VerifyResult:
+        data = self._request("POST", "/api/v1/verify", json={"email": email})
+        return VerifyResult.from_dict(data)
+
+    def credits(self) -> CreditsInfo:
+        return CreditsInfo.from_dict(self._request("GET", "/api/v1/credits"))
+
+    def bulk(
+        self,
+        emails: list[str],
+        *,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        webhook_secret: Optional[str] = None,
+    ) -> CreateBulkResponse:
+        body: dict[str, Any] = {"emails": emails}
+        if filename:
+            body["filename"] = filename
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if webhook_secret:
+            body["webhook_secret"] = webhook_secret
+        data = self._request("POST", "/api/v1/bulk", json=body)
+        return CreateBulkResponse.from_dict(data)
+
+    def bulk_status(self, job_id: str) -> BulkJob:
+        data = self._request("GET", f"/api/v1/bulk/{quote(job_id, safe='')}")
+        return BulkJob.from_dict(data["job"])
+
+    def bulk_cancel(self, job_id: str) -> BulkJob:
+        data = self._request("DELETE", f"/api/v1/bulk/{quote(job_id, safe='')}")
+        return BulkJob.from_dict(data["job"])
+
+    def bulk_download_url(self, job_id: str) -> DownloadResponse:
+        return DownloadResponse.from_dict(
+            self._request("GET", f"/api/v1/bulk/{quote(job_id, safe='')}/download")
+        )
+
+    def bulk_set_webhook(
+        self, job_id: str, *, webhook_url: str, webhook_secret: Optional[str] = None
+    ) -> SetWebhookResponse:
+        body: dict[str, Any] = {"webhook_url": webhook_url}
+        if webhook_secret:
+            body["webhook_secret"] = webhook_secret
+        data = self._request(
+            "POST", f"/api/v1/bulk/{quote(job_id, safe='')}/webhook", json=body
+        )
+        return SetWebhookResponse.from_dict(data)
+
+    def bulk_wait_for_completion(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = 3.0,
+        timeout_seconds: Optional[float] = None,
+        on_progress: Optional[Callable[[BulkJob], None]] = None,
+    ) -> BulkJob:
+        deadline = time.monotonic() + timeout_seconds if timeout_seconds else None
+        while True:
+            job = self.bulk_status(job_id)
+            if on_progress:
+                on_progress(job)
+            if job.status in TERMINAL_STATUSES:
+                return job
+            if deadline and time.monotonic() + interval_seconds > deadline:
+                raise TimeoutError(
+                    f"bulk_wait_for_completion timed out after {timeout_seconds}s"
+                )
+            time.sleep(interval_seconds)
+
+    def bulk_and_wait(
+        self,
+        emails: list[str],
+        *,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        interval_seconds: float = 3.0,
+        timeout_seconds: Optional[float] = None,
+        on_progress: Optional[Callable[[BulkJob], None]] = None,
+    ) -> tuple[BulkJob, str]:
+        created = self.bulk(emails=emails, filename=filename, webhook_url=webhook_url)
+        job = created.job
+        final = self.bulk_wait_for_completion(
+            job.id,
+            interval_seconds=interval_seconds,
+            timeout_seconds=timeout_seconds,
+            on_progress=on_progress,
+        )
+        if final.status != "completed" or not final.result_available:
+            raise ByeBouncerError(
+                code="bulk_not_completed", status=0, detail=f"status={final.status}"
+            )
+        download = self.bulk_download_url(final.id)
+        csv_res = self._client.get(download.url)
+        if csv_res.status_code >= 300:
+            raise ByeBouncerError(
+                code="csv_download_failed",
+                status=csv_res.status_code,
+                detail=csv_res.text[:200],
+            )
+        return final, csv_res.text
+
+    # ─── Internal ────────────────────────────────────────────
+
+    def _headers(self, has_body: bool) -> dict[str, str]:
+        h = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": USER_AGENT,
+        }
+        if has_body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _request(self, method: str, path: str, *, json: Any = None) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        res = self._client.request(
+            method, url, headers=self._headers(json is not None), json=json
+        )
+        if res.status_code >= 300:
+            raise _parse_error(res)
+        if not res.content:
+            return {}
+        return res.json()
+
+
+class AsyncByeBouncer:
+    """Async client using httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncByeBouncer":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def verify(self, email: str) -> VerifyResult:
+        data = await self._request("POST", "/api/v1/verify", json={"email": email})
+        return VerifyResult.from_dict(data)
+
+    async def credits(self) -> CreditsInfo:
+        return CreditsInfo.from_dict(await self._request("GET", "/api/v1/credits"))
+
+    async def bulk(
+        self,
+        emails: list[str],
+        *,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        webhook_secret: Optional[str] = None,
+    ) -> CreateBulkResponse:
+        body: dict[str, Any] = {"emails": emails}
+        if filename:
+            body["filename"] = filename
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        if webhook_secret:
+            body["webhook_secret"] = webhook_secret
+        data = await self._request("POST", "/api/v1/bulk", json=body)
+        return CreateBulkResponse.from_dict(data)
+
+    async def bulk_status(self, job_id: str) -> BulkJob:
+        data = await self._request("GET", f"/api/v1/bulk/{quote(job_id, safe='')}")
+        return BulkJob.from_dict(data["job"])
+
+    async def bulk_cancel(self, job_id: str) -> BulkJob:
+        data = await self._request("DELETE", f"/api/v1/bulk/{quote(job_id, safe='')}")
+        return BulkJob.from_dict(data["job"])
+
+    async def bulk_download_url(self, job_id: str) -> DownloadResponse:
+        return DownloadResponse.from_dict(
+            await self._request("GET", f"/api/v1/bulk/{quote(job_id, safe='')}/download")
+        )
+
+    async def bulk_set_webhook(
+        self, job_id: str, *, webhook_url: str, webhook_secret: Optional[str] = None
+    ) -> SetWebhookResponse:
+        body: dict[str, Any] = {"webhook_url": webhook_url}
+        if webhook_secret:
+            body["webhook_secret"] = webhook_secret
+        data = await self._request(
+            "POST", f"/api/v1/bulk/{quote(job_id, safe='')}/webhook", json=body
+        )
+        return SetWebhookResponse.from_dict(data)
+
+    async def bulk_wait_for_completion(
+        self,
+        job_id: str,
+        *,
+        interval_seconds: float = 3.0,
+        timeout_seconds: Optional[float] = None,
+        on_progress: Optional[Callable[[BulkJob], None]] = None,
+    ) -> BulkJob:
+        deadline = time.monotonic() + timeout_seconds if timeout_seconds else None
+        while True:
+            job = await self.bulk_status(job_id)
+            if on_progress:
+                on_progress(job)
+            if job.status in TERMINAL_STATUSES:
+                return job
+            if deadline and time.monotonic() + interval_seconds > deadline:
+                raise TimeoutError(
+                    f"bulk_wait_for_completion timed out after {timeout_seconds}s"
+                )
+            await asyncio.sleep(interval_seconds)
+
+    async def bulk_and_wait(
+        self,
+        emails: list[str],
+        *,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        interval_seconds: float = 3.0,
+        timeout_seconds: Optional[float] = None,
+        on_progress: Optional[Callable[[BulkJob], None]] = None,
+    ) -> tuple[BulkJob, str]:
+        created = await self.bulk(
+            emails=emails, filename=filename, webhook_url=webhook_url
+        )
+        final = await self.bulk_wait_for_completion(
+            created.job.id,
+            interval_seconds=interval_seconds,
+            timeout_seconds=timeout_seconds,
+            on_progress=on_progress,
+        )
+        if final.status != "completed" or not final.result_available:
+            raise ByeBouncerError(
+                code="bulk_not_completed", status=0, detail=f"status={final.status}"
+            )
+        download = await self.bulk_download_url(final.id)
+        csv_res = await self._client.get(download.url)
+        if csv_res.status_code >= 300:
+            raise ByeBouncerError(
+                code="csv_download_failed",
+                status=csv_res.status_code,
+                detail=csv_res.text[:200],
+            )
+        return final, csv_res.text
+
+    def _headers(self, has_body: bool) -> dict[str, str]:
+        h = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": USER_AGENT,
+        }
+        if has_body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    async def _request(self, method: str, path: str, *, json: Any = None) -> dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        res = await self._client.request(
+            method, url, headers=self._headers(json is not None), json=json
+        )
+        if res.status_code >= 300:
+            raise _parse_error(res)
+        if not res.content:
+            return {}
+        return res.json()

byebouncer-0.1.0/byebouncer/errors.py

@@ -0,0 +1,55 @@
+"""Exceptions raised by the SDK on non-2xx responses."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ByeBouncerError(Exception):
+    """Base error. Access `code`, `status`, and `detail`."""
+
+    def __init__(
+        self,
+        code: str,
+        status: int,
+        detail: Optional[str] = None,
+        response: Optional[Any] = None,
+    ) -> None:
+        super().__init__(detail or code)
+        self.code = code
+        self.status = status
+        self.detail = detail
+        self.response = response
+
+
+class UnauthorizedError(ByeBouncerError):
+    """Raised on HTTP 401."""
+
+    def __init__(self, detail: Optional[str] = None, response: Optional[Any] = None) -> None:
+        super().__init__("invalid_api_key", 401, detail, response)
+
+
+class InsufficientCreditsError(ByeBouncerError):
+    """Raised on HTTP 402."""
+
+    def __init__(
+        self,
+        detail: Optional[str] = None,
+        response: Optional[Any] = None,
+        credits_remaining: Optional[int] = None,
+    ) -> None:
+        super().__init__("insufficient_credits", 402, detail, response)
+        self.credits_remaining = credits_remaining
+
+
+class RateLimitError(ByeBouncerError):
+    """Raised on HTTP 429."""
+
+    def __init__(
+        self,
+        detail: Optional[str] = None,
+        response: Optional[Any] = None,
+        retry_after_seconds: Optional[int] = None,
+    ) -> None:
+        super().__init__("rate_limited", 429, detail, response)
+        self.retry_after_seconds = retry_after_seconds

byebouncer-0.1.0/byebouncer/models.py

@@ -0,0 +1,179 @@
+"""Response models mirroring docs/api/openapi.yaml.
+
+We keep them as plain dataclasses so the SDK stays dependency-light and Pydantic
+version conflicts don't affect users. All fields are populated from the parsed
+JSON response dict.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+VerifyStatus = Literal["deliverable", "undeliverable", "risky", "unknown"]
+VerifyAction = Literal["allow", "review", "block"]
+DomainType = Literal["business", "free", "disposable", "education", "unknown"]
+BulkJobStatus = Literal[
+    "pending", "processing", "completed", "failed", "cancelled", "expired"
+]
+
+
+@dataclass
+class DomainInfo:
+    name: str
+    type: DomainType
+    disposable: bool
+    free_provider: bool
+    has_mx: bool
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "DomainInfo":
+        return cls(
+            name=d["name"],
+            type=d["type"],
+            disposable=d["disposable"],
+            free_provider=d["free_provider"],
+            has_mx=d["has_mx"],
+        )
+
+
+@dataclass
+class VerifyResult:
+    email: str
+    status: VerifyStatus
+    action: VerifyAction
+    flagged: bool
+    signals: list[str]
+    domain: DomainInfo
+    cached: bool
+    response_time_ms: int
+    verified_at: str
+    credits_remaining: int
+    suggestion: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "VerifyResult":
+        return cls(
+            email=d["email"],
+            status=d["status"],
+            action=d["action"],
+            flagged=d["flagged"],
+            signals=list(d.get("signals") or []),
+            domain=DomainInfo.from_dict(d["domain"]),
+            cached=d["cached"],
+            response_time_ms=d["response_time_ms"],
+            verified_at=d["verified_at"],
+            credits_remaining=d["credits_remaining"],
+            suggestion=d.get("suggestion"),
+        )
+
+
+@dataclass
+class CreditsInfo:
+    api_key_id: str
+    key_prefix: str
+    credits: int
+    auto_topup: bool
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "CreditsInfo":
+        return cls(
+            api_key_id=d["api_key_id"],
+            key_prefix=d["key_prefix"],
+            credits=d["credits"],
+            auto_topup=d["auto_topup"],
+        )
+
+
+@dataclass
+class BulkJob:
+    id: str
+    source: Literal["api", "dashboard"]
+    status: BulkJobStatus
+    total_emails: int
+    processed: int
+    valid: int
+    invalid: int
+    unknown: int
+    credits_debited: int
+    credits_refunded: int
+    result_available: bool
+    created_at: str
+    expires_at: str
+    filename: Optional[str] = None
+    webhook_url: Optional[str] = None
+    error_message: Optional[str] = None
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    estimated_seconds_remaining: Optional[int] = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "BulkJob":
+        return cls(
+            id=d["id"],
+            source=d["source"],
+            status=d["status"],
+            total_emails=d["total_emails"],
+            processed=d["processed"],
+            valid=d["valid"],
+            invalid=d["invalid"],
+            unknown=d["unknown"],
+            credits_debited=d["credits_debited"],
+            credits_refunded=d["credits_refunded"],
+            result_available=d["result_available"],
+            created_at=d["created_at"],
+            expires_at=d["expires_at"],
+            filename=d.get("filename"),
+            webhook_url=d.get("webhook_url"),
+            error_message=d.get("error_message"),
+            started_at=d.get("started_at"),
+            completed_at=d.get("completed_at"),
+            estimated_seconds_remaining=d.get("estimated_seconds_remaining"),
+            raw=d,
+        )
+
+
+@dataclass
+class DownloadResponse:
+    url: str
+    expires_in_seconds: int
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "DownloadResponse":
+        return cls(url=d["url"], expires_in_seconds=d["expires_in_seconds"])
+
+
+@dataclass
+class CreateBulkResponse:
+    job: BulkJob
+    estimated_seconds: int
+    webhook_secret: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "CreateBulkResponse":
+        return cls(
+            job=BulkJob.from_dict(d["job"]),
+            estimated_seconds=d["estimated_seconds"],
+            webhook_secret=d.get("webhook_secret"),
+        )
+
+
+@dataclass
+class SetWebhookResponse:
+    job_id: str
+    webhook_url: str
+    webhook_secret: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "SetWebhookResponse":
+        return cls(
+            job_id=d["job_id"],
+            webhook_url=d["webhook_url"],
+            webhook_secret=d["webhook_secret"],
+        )
+
+
+TERMINAL_STATUSES: frozenset[BulkJobStatus] = frozenset(
+    {"completed", "failed", "cancelled", "expired"}
+)

byebouncer-0.1.0/byebouncer/py.typed

@@ -0,0 +1 @@
+

byebouncer-0.1.0/examples/bulk_async.py

@@ -0,0 +1,35 @@
+"""Async bulk verification example.
+Run: BB_API_KEY=bb_live_... python examples/bulk_async.py"""
+
+import asyncio
+import os
+
+from byebouncer import AsyncByeBouncer
+
+
+async def main() -> None:
+    async with AsyncByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+        created = await client.bulk(
+            emails=["a@gmail.com", "b@outlook.com", "invalid@nomxexists.tld"],
+            filename="sdk_example.csv",
+        )
+        job = created.job
+        print(f"Job {job.id} enqueued, {job.total_emails} emails")
+
+        final = await client.bulk_wait_for_completion(
+            job.id,
+            interval_seconds=3,
+            on_progress=lambda j: print(
+                f"[{j.status}] {j.processed}/{j.total_emails}"
+            ),
+        )
+        print(
+            f"Done: valid={final.valid} invalid={final.invalid} unknown={final.unknown}"
+        )
+
+        if final.status == "completed":
+            download = await client.bulk_download_url(final.id)
+            print(f"Download URL (valid {download.expires_in_seconds}s): {download.url}")
+
+
+asyncio.run(main())

byebouncer-0.1.0/examples/verify.py

@@ -0,0 +1,12 @@
+"""Single-email verification example.
+Run: BB_API_KEY=bb_live_... python examples/verify.py"""
+
+import os
+
+from byebouncer import ByeBouncer
+
+with ByeBouncer(api_key=os.environ["BB_API_KEY"]) as client:
+    result = client.verify("user@gmail.com")
+    print(f"{result.email} → {result.status} ({result.action})")
+    print(f"Signals: {', '.join(result.signals)}")
+    print(f"Credits left: {result.credits_remaining}")

byebouncer-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "byebouncer"
+version = "0.1.0"
+description = "Official Python SDK for the ByeBouncer email verification API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "ByeBouncer", email = "hello@byebouncer.com" }]
+keywords = ["email", "verification", "bounce", "smtp", "email-validation"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+]
+dependencies = [
+  "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://byebouncer.com"
+Documentation = "https://byebouncer.com/docs"
+Repository = "https://github.com/fidelp27/byebouncer"
+Issues = "https://github.com/fidelp27/byebouncer/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["byebouncer"]
+
+[tool.hatch.build.targets.sdist]
+include = ["byebouncer", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "B", "SIM"]
+ignore = ["SIM117"] # Nested context managers preserve Python 3.9 syntax compatibility.

byebouncer-0.1.0/tests/test_client.py

@@ -0,0 +1,197 @@
+"""Tests for the sync + async clients using respx mocks."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from byebouncer import (
+    AsyncByeBouncer,
+    ByeBouncer,
+    InsufficientCreditsError,
+    UnauthorizedError,
+)
+
+BASE = "https://api.example.com"
+
+
+def _verify_payload() -> dict:
+    return {
+        "email": "jane@gmail.com",
+        "status": "deliverable",
+        "action": "allow",
+        "flagged": False,
+        "signals": ["valid_syntax"],
+        "domain": {
+            "name": "gmail.com",
+            "type": "free",
+            "disposable": False,
+            "free_provider": True,
+            "has_mx": True,
+        },
+        "cached": False,
+        "response_time_ms": 184,
+        "verified_at": "2026-09-05T23:30:00Z",
+        "credits_remaining": 4999,
+    }
+
+
+def _bulk_job_payload(*, status: str = "pending", result_available: bool = False) -> dict:
+    return {
+        "id": "job_1",
+        "source": "api",
+        "status": status,
+        "total_emails": 2,
+        "processed": 2 if status == "completed" else 0,
+        "valid": 2 if status == "completed" else 0,
+        "invalid": 0,
+        "unknown": 0,
+        "credits_debited": 2,
+        "credits_refunded": 0,
+        "result_available": result_available,
+        "created_at": "2026-09-05T00:00:00Z",
+        "expires_at": "2026-09-12T00:00:00Z",
+    }
+
+
+@respx.mock
+def test_verify_returns_result():
+    respx.post(f"{BASE}/api/v1/verify").mock(
+        return_value=httpx.Response(200, json=_verify_payload())
+    )
+    with ByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        result = client.verify("jane@gmail.com")
+    assert result.status == "deliverable"
+    assert result.credits_remaining == 4999
+    assert result.domain.free_provider is True
+
+
+@respx.mock
+def test_verify_401_raises_unauthorized():
+    respx.post(f"{BASE}/api/v1/verify").mock(
+        return_value=httpx.Response(401, json={"error": "invalid_api_key"})
+    )
+    with ByeBouncer(api_key="bb_live_bad", base_url=BASE) as client:
+        with pytest.raises(UnauthorizedError):
+            client.verify("x@y.com")
+
+
+@respx.mock
+def test_verify_402_raises_insufficient_credits():
+    respx.post(f"{BASE}/api/v1/verify").mock(
+        return_value=httpx.Response(
+            402, json={"error": "insufficient_credits", "credits_remaining": 0}
+        )
+    )
+    with ByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        with pytest.raises(InsufficientCreditsError) as excinfo:
+            client.verify("x@y.com")
+    assert excinfo.value.credits_remaining == 0
+
+
+@respx.mock
+def test_bulk_returns_job():
+    respx.post(f"{BASE}/api/v1/bulk").mock(
+        return_value=httpx.Response(
+            202,
+            json={
+                "job": _bulk_job_payload(),
+                "estimated_seconds": 5,
+                "webhook_secret": "generated-secret",
+            },
+        )
+    )
+    with ByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        created = client.bulk(
+            emails=["a@x.com", "b@y.com"],
+            webhook_url="https://example.com/webhook",
+        )
+    assert created.job.id == "job_1"
+    assert created.job.status == "pending"
+    assert created.estimated_seconds == 5
+    assert created.webhook_secret == "generated-secret"
+
+
+@respx.mock
+def test_bulk_set_webhook_returns_typed_secret():
+    respx.post(f"{BASE}/api/v1/bulk/job_1/webhook").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "job_id": "job_1",
+                "webhook_url": "https://example.com/webhook",
+                "webhook_secret": "generated-secret",
+            },
+        )
+    )
+    with ByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        webhook = client.bulk_set_webhook(
+            "job_1", webhook_url="https://example.com/webhook"
+        )
+    assert webhook.job_id == "job_1"
+    assert webhook.webhook_secret == "generated-secret"
+
+
+@respx.mock
+async def test_async_verify():
+    respx.post(f"{BASE}/api/v1/verify").mock(
+        return_value=httpx.Response(200, json=_verify_payload())
+    )
+    async with AsyncByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        result = await client.verify("jane@gmail.com")
+    assert result.status == "deliverable"
+
+
+@respx.mock
+async def test_async_bulk_exposes_generated_webhook_secret():
+    respx.post(f"{BASE}/api/v1/bulk").mock(
+        return_value=httpx.Response(
+            202,
+            json={
+                "job": _bulk_job_payload(),
+                "estimated_seconds": 5,
+                "webhook_secret": "generated-secret",
+            },
+        )
+    )
+    async with AsyncByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        created = await client.bulk(
+            emails=["a@x.com", "b@y.com"],
+            webhook_url="https://example.com/webhook",
+        )
+    assert created.job.id == "job_1"
+    assert created.webhook_secret == "generated-secret"
+
+
+@respx.mock
+async def test_async_bulk_and_wait_downloads_csv():
+    respx.post(f"{BASE}/api/v1/bulk").mock(
+        return_value=httpx.Response(
+            202,
+            json={"job": _bulk_job_payload(), "estimated_seconds": 5},
+        )
+    )
+    respx.get(f"{BASE}/api/v1/bulk/job_1").mock(
+        return_value=httpx.Response(
+            200,
+            json={"job": _bulk_job_payload(status="completed", result_available=True)},
+        )
+    )
+    respx.get(f"{BASE}/api/v1/bulk/job_1/download").mock(
+        return_value=httpx.Response(
+            200,
+            json={"url": "https://storage.example.com/result.csv", "expires_in_seconds": 86400},
+        )
+    )
+    respx.get("https://storage.example.com/result.csv").mock(
+        return_value=httpx.Response(200, text="email,status\na@x.com,deliverable\n")
+    )
+
+    async with AsyncByeBouncer(api_key="bb_live_test", base_url=BASE) as client:
+        job, csv = await client.bulk_and_wait(
+            emails=["a@x.com", "b@y.com"], interval_seconds=0.001
+        )
+
+    assert job.status == "completed"
+    assert "a@x.com,deliverable" in csv