verifly-email 1.0.0__tar.gz

verifly_email-1.0.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: verifly-email
+Version: 1.0.0
+Summary: Official Python SDK for the Verifly email-verification API (verifly.email)
+Author: Verifly
+License: MIT
+Project-URL: Homepage, https://verifly.email
+Project-URL: Documentation, https://verifly.email/docs/api
+Project-URL: API Spec, https://verifly.email/openapi.json
+Keywords: email,verification,validation,verifly,deliverability
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# verifly-email (Python)
+
+Official Python SDK for the [Verifly](https://verifly.email) email-verification API.
+
+> **Package naming.** Install **`verifly-email`** and import **`verifly_email`**.
+> The plain name `verifly` on PyPI belongs to an **unrelated 2FA company** — it
+> is *not* this project. Always use `verifly-email`.
+
+- Zero dependencies (pure Python standard library).
+- Fully typed, with docstrings on every method.
+- Built-in retry with backoff on `429` / `5xx` (honors `Retry-After`).
+- Automatic `Idempotency-Key` for `buy_credits` and `submit_bulk`.
+- Typed `VeriflyError(code, message, request_id)` on API error envelopes.
+
+## Install
+
+```bash
+pip install verifly-email          # once published
+# or, from this repo:
+pip install /path/to/sdks/python
+```
+
+## Quick start
+
+```python
+from verifly_email import VeriflyClient, VeriflyError
+
+client = VeriflyClient("vf_your_api_key")   # base_url defaults to https://verifly.email
+
+try:
+    r = client.verify("bill.gates@microsoft.com")
+    print(r["result"])           # deliverable | undeliverable | risky | unknown
+    print(r["recommendation"])   # safe_to_send | risky | do_not_send
+    print(r["credits"])          # {"used": 1, "remaining": 99}
+except VeriflyError as e:
+    print(e.code, e.message, e.request_id)
+```
+
+## Authentication
+
+Every call (except `register`) authenticates with your `vf_` key, sent as
+`Authorization: Bearer <api_key>`.
+
+```python
+client = VeriflyClient(api_key="vf_...", base_url="https://verifly.email")
+```
+
+## Create an account programmatically
+
+```python
+res = VeriflyClient.register("you@example.com", "a-strong-password")
+api_key = res["api_key"]["key"]   # shown ONCE — store it now
+client = VeriflyClient(api_key)
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `verify(email)` | Verify a single address. |
+| `verify_batch(emails, deduplicate=True, ...)` | Verify up to 100 addresses synchronously. |
+| `clean(emails, options=None)` | Clean/filter a list (no verification, no credits). |
+| `extract(text, deduplicate=True, lowercase=True)` | Pull email addresses out of text/CSV. |
+| `submit_bulk(emails=None, text=None, webhook_url=None, ...)` | Create an async bulk job (up to 1M). |
+| `jobs(status=None, limit=None, offset=None)` | List bulk jobs. |
+| `job(job_id)` | Get a bulk job's status. |
+| `job_results(job_id)` | Get a completed job's per-email results. |
+| `account()` | Account profile + credit summary. |
+| `credits()` | Current credit balance. |
+| `usage(period=None, limit=None)` | API usage summary (day/week/month). |
+| `packages()` | List credit packages and prices. |
+| `payment_history()` | List payment history. |
+| `buy_credits(package_id, method="stripe", currency=None)` | Create a Stripe/crypto checkout. |
+| `VeriflyClient.register(email, password)` *(classmethod)* | Self-register, returns account + API key. |
+
+### Examples
+
+```python
+# Batch (<=100), synchronous
+batch = client.verify_batch(
+    ["a@example.com", "b@example.com"],
+    exclude_role_accounts=True,
+)
+for item in batch["results"]:
+    print(item["email"], item["result"])
+
+# List hygiene without spending credits
+print(client.clean(["A@Example.com ", "a@example.com", "bad"])["..."])
+print(client.extract("contact us at sales@acme.io or ceo@acme.io"))
+
+# Async bulk + polling
+job = client.submit_bulk(emails=[...], webhook_url="https://you/webhook")
+status = client.job(job["job_id"] if "job_id" in job else job["job"]["id"])
+results = client.job_results(job_id)
+
+# Account / billing
+print(client.credits())
+print(client.packages())
+checkout = client.buy_credits("pro", method="stripe")
+checkout = client.buy_credits("pro", method="crypto", currency="USDT")
+```
+
+## Errors
+
+API error envelopes (`{"success": false, "error": {...}}`) and non-2xx
+responses raise `VeriflyError`:
+
+```python
+try:
+    client.verify("nope")
+except VeriflyError as e:
+    e.code         # e.g. "invalid_email", "insufficient_credits", "rate_limit_exceeded"
+    e.message
+    e.request_id   # from the x-request-id response header
+    e.status       # HTTP status
+    e.suggestion   # optional remediation hint
+```
+
+## Retries & idempotency
+
+- `429` and `5xx` responses are retried (default 3 times) with exponential
+  backoff, honoring the `Retry-After` header. Configure via
+  `VeriflyClient(..., max_retries=N, timeout=seconds)`.
+- `buy_credits` and `submit_bulk` send an `Idempotency-Key` header. One is
+  auto-generated per call; pass your own with `idempotency_key=...` to make a
+  specific retry safe end-to-end.
+
+## License
+
+MIT

verifly_email-1.0.0/README.md

@@ -0,0 +1,130 @@
+# verifly-email (Python)
+
+Official Python SDK for the [Verifly](https://verifly.email) email-verification API.
+
+> **Package naming.** Install **`verifly-email`** and import **`verifly_email`**.
+> The plain name `verifly` on PyPI belongs to an **unrelated 2FA company** — it
+> is *not* this project. Always use `verifly-email`.
+
+- Zero dependencies (pure Python standard library).
+- Fully typed, with docstrings on every method.
+- Built-in retry with backoff on `429` / `5xx` (honors `Retry-After`).
+- Automatic `Idempotency-Key` for `buy_credits` and `submit_bulk`.
+- Typed `VeriflyError(code, message, request_id)` on API error envelopes.
+
+## Install
+
+```bash
+pip install verifly-email          # once published
+# or, from this repo:
+pip install /path/to/sdks/python
+```
+
+## Quick start
+
+```python
+from verifly_email import VeriflyClient, VeriflyError
+
+client = VeriflyClient("vf_your_api_key")   # base_url defaults to https://verifly.email
+
+try:
+    r = client.verify("bill.gates@microsoft.com")
+    print(r["result"])           # deliverable | undeliverable | risky | unknown
+    print(r["recommendation"])   # safe_to_send | risky | do_not_send
+    print(r["credits"])          # {"used": 1, "remaining": 99}
+except VeriflyError as e:
+    print(e.code, e.message, e.request_id)
+```
+
+## Authentication
+
+Every call (except `register`) authenticates with your `vf_` key, sent as
+`Authorization: Bearer <api_key>`.
+
+```python
+client = VeriflyClient(api_key="vf_...", base_url="https://verifly.email")
+```
+
+## Create an account programmatically
+
+```python
+res = VeriflyClient.register("you@example.com", "a-strong-password")
+api_key = res["api_key"]["key"]   # shown ONCE — store it now
+client = VeriflyClient(api_key)
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `verify(email)` | Verify a single address. |
+| `verify_batch(emails, deduplicate=True, ...)` | Verify up to 100 addresses synchronously. |
+| `clean(emails, options=None)` | Clean/filter a list (no verification, no credits). |
+| `extract(text, deduplicate=True, lowercase=True)` | Pull email addresses out of text/CSV. |
+| `submit_bulk(emails=None, text=None, webhook_url=None, ...)` | Create an async bulk job (up to 1M). |
+| `jobs(status=None, limit=None, offset=None)` | List bulk jobs. |
+| `job(job_id)` | Get a bulk job's status. |
+| `job_results(job_id)` | Get a completed job's per-email results. |
+| `account()` | Account profile + credit summary. |
+| `credits()` | Current credit balance. |
+| `usage(period=None, limit=None)` | API usage summary (day/week/month). |
+| `packages()` | List credit packages and prices. |
+| `payment_history()` | List payment history. |
+| `buy_credits(package_id, method="stripe", currency=None)` | Create a Stripe/crypto checkout. |
+| `VeriflyClient.register(email, password)` *(classmethod)* | Self-register, returns account + API key. |
+
+### Examples
+
+```python
+# Batch (<=100), synchronous
+batch = client.verify_batch(
+    ["a@example.com", "b@example.com"],
+    exclude_role_accounts=True,
+)
+for item in batch["results"]:
+    print(item["email"], item["result"])
+
+# List hygiene without spending credits
+print(client.clean(["A@Example.com ", "a@example.com", "bad"])["..."])
+print(client.extract("contact us at sales@acme.io or ceo@acme.io"))
+
+# Async bulk + polling
+job = client.submit_bulk(emails=[...], webhook_url="https://you/webhook")
+status = client.job(job["job_id"] if "job_id" in job else job["job"]["id"])
+results = client.job_results(job_id)
+
+# Account / billing
+print(client.credits())
+print(client.packages())
+checkout = client.buy_credits("pro", method="stripe")
+checkout = client.buy_credits("pro", method="crypto", currency="USDT")
+```
+
+## Errors
+
+API error envelopes (`{"success": false, "error": {...}}`) and non-2xx
+responses raise `VeriflyError`:
+
+```python
+try:
+    client.verify("nope")
+except VeriflyError as e:
+    e.code         # e.g. "invalid_email", "insufficient_credits", "rate_limit_exceeded"
+    e.message
+    e.request_id   # from the x-request-id response header
+    e.status       # HTTP status
+    e.suggestion   # optional remediation hint
+```
+
+## Retries & idempotency
+
+- `429` and `5xx` responses are retried (default 3 times) with exponential
+  backoff, honoring the `Retry-After` header. Configure via
+  `VeriflyClient(..., max_retries=N, timeout=seconds)`.
+- `buy_credits` and `submit_bulk` send an `Idempotency-Key` header. One is
+  auto-generated per call; pass your own with `idempotency_key=...` to make a
+  specific retry safe end-to-end.
+
+## License
+
+MIT

verifly_email-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "verifly-email"
+version = "1.0.0"
+description = "Official Python SDK for the Verifly email-verification API (verifly.email)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Verifly" }]
+keywords = ["email", "verification", "validation", "verifly", "deliverability"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://verifly.email"
+Documentation = "https://verifly.email/docs/api"
+"API Spec" = "https://verifly.email/openapi.json"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["verifly_email"]
+
+[tool.setuptools.package-data]
+verifly_email = ["py.typed"]

verifly_email-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

verifly_email-1.0.0/verifly_email/__init__.py

@@ -0,0 +1,16 @@
+"""Official Python SDK for the Verifly email-verification API (https://verifly.email).
+
+PyPI package name: ``verifly-email``  (import as ``verifly_email``).
+
+Quick start::
+
+    from verifly_email import VeriflyClient
+
+    client = VeriflyClient("vf_your_api_key")
+    result = client.verify("bill.gates@microsoft.com")
+    print(result["result"], result["recommendation"])
+"""
+
+from .client import VeriflyClient, VeriflyError, __version__
+
+__all__ = ["VeriflyClient", "VeriflyError", "__version__"]

verifly_email-1.0.0/verifly_email/client.py

@@ -0,0 +1,465 @@
+"""Verifly API client.
+
+Zero third-party dependencies: built on the Python standard library only
+(``urllib``), so it installs and runs anywhere with no extra packages.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Optional, Sequence
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://verifly.email"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+_USER_AGENT = f"verifly-email-python/{__version__}"
+
+JSON = Dict[str, Any]
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Redirect handler that never leaks credentials across origins.
+
+    ``urllib`` follows 3xx redirects automatically and, by default, forwards
+    every request header -- including ``Authorization`` -- to the redirect
+    target even when it points at a different scheme/host. That would leak the
+    ``vf_`` API key to an unrelated server. This strips the ``Authorization``
+    header whenever a redirect crosses to a different scheme, host, or port.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new_req = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_req is not None:
+            old = urllib.parse.urlsplit(req.full_url)
+            new = urllib.parse.urlsplit(newurl)
+            if (old.scheme, old.hostname, old.port) != (
+                new.scheme,
+                new.hostname,
+                new.port,
+            ):
+                new_req.headers.pop("Authorization", None)
+                new_req.unredirected_hdrs.pop("Authorization", None)
+        return new_req
+
+
+class VeriflyError(Exception):
+    """Raised when the Verifly API returns an error envelope or the request fails.
+
+    Attributes:
+        code: Machine-readable error code (e.g. ``invalid_api_key``,
+            ``insufficient_credits``, ``rate_limit_exceeded``). ``http_error``
+            for transport-level failures.
+        message: Human-readable explanation.
+        request_id: Server request id, when provided (from the
+            ``x-request-id`` response header).
+        status: HTTP status code, when available.
+        suggestion: Optional remediation hint from the API.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        status: Optional[int] = None,
+        suggestion: Optional[str] = None,
+    ) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.status = status
+        self.suggestion = suggestion
+
+
+class VeriflyClient:
+    """Typed client for the Verifly email-verification API.
+
+    Args:
+        api_key: Your ``vf_`` API key. Sent as ``Authorization: Bearer <key>``.
+            Not required for :meth:`register`.
+        base_url: API base URL. Defaults to ``https://verifly.email``.
+        timeout: Per-request timeout in seconds.
+        max_retries: Number of retries on 429 / 5xx responses (with backoff,
+            honoring ``Retry-After``).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        # Open requests through a handler that strips Authorization on
+        # cross-origin redirects so the API key can never leak to another host.
+        self._opener = urllib.request.build_opener(_SafeRedirectHandler())
+
+    # ------------------------------------------------------------------ #
+    # Account lifecycle
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def register(
+        cls,
+        email: str,
+        password: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> JSON:
+        """Self-register a new account and receive an API key (100 free credits).
+
+        The full API key is shown exactly once, under ``result["api_key"]["key"]``.
+
+        Returns the ``RegisterResult`` envelope: ``{success, message, account,
+        api_key}``.
+        """
+        client = cls(api_key=None, base_url=base_url, timeout=timeout)
+        return client._request(
+            "POST",
+            "/api/v1/autonomous/register",
+            body={"email": email, "password": password},
+            auth=False,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Verification
+    # ------------------------------------------------------------------ #
+    def verify(self, email: str) -> JSON:
+        """Verify a single email address.
+
+        Returns a ``VerificationResult``: ``{success, email, is_valid, result
+        (deliverable|undeliverable|risky|unknown), reason, details{...},
+        recommendation (safe_to_send|risky|do_not_send), credits_charged,
+        credits{used,remaining}}``.
+        """
+        return self._request("GET", "/api/v1/verify", query={"email": email})
+
+    def verify_batch(
+        self,
+        emails: Sequence[str],
+        deduplicate: bool = True,
+        exclude_public_domains: bool = False,
+        exclude_role_accounts: bool = False,
+        domain_blacklist: Optional[Sequence[str]] = None,
+        pattern_blacklist: Optional[Sequence[str]] = None,
+    ) -> JSON:
+        """Verify up to 100 emails synchronously.
+
+        Returns a ``BatchVerificationResult`` with a ``results`` array.
+        """
+        options: JSON = {
+            "deduplicate": deduplicate,
+            "exclude_public_domains": exclude_public_domains,
+            "exclude_role_accounts": exclude_role_accounts,
+        }
+        if domain_blacklist is not None:
+            options["domain_blacklist"] = list(domain_blacklist)
+        if pattern_blacklist is not None:
+            options["pattern_blacklist"] = list(pattern_blacklist)
+        return self._request(
+            "POST",
+            "/api/v1/verify/batch",
+            body={"emails": list(emails), "options": options},
+        )
+
+    def submit_bulk(
+        self,
+        emails: Optional[Sequence[str]] = None,
+        text: Optional[str] = None,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """Create an asynchronous bulk verification job.
+
+        Provide either ``emails`` (up to 1,000,000) or raw ``text``/CSV to
+        extract addresses from. ``webhook_url`` is called when the job
+        completes. Returns a ``BulkJobResult`` with the job id; poll with
+        :meth:`job` and fetch output with :meth:`job_results`.
+
+        ``idempotency_key`` is passed through as the ``Idempotency-Key`` header;
+        if omitted, one is generated automatically so retries are safe.
+        """
+        if emails is None and text is None:
+            raise ValueError("submit_bulk requires either 'emails' or 'text'")
+        body: JSON = {}
+        if emails is not None:
+            body["emails"] = list(emails)
+        if text is not None:
+            body["text"] = text
+        if filename is not None:
+            body["filename"] = filename
+        if webhook_url is not None:
+            body["webhook_url"] = webhook_url
+        return self._request(
+            "POST",
+            "/api/v1/verify/bulk",
+            body=body,
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+
+    # ------------------------------------------------------------------ #
+    # List hygiene
+    # ------------------------------------------------------------------ #
+    def clean(
+        self,
+        emails: Sequence[str],
+        options: Optional[JSON] = None,
+    ) -> JSON:
+        """Clean and filter an email list (dedupe, syntax, role/disposable, etc).
+
+        Does not verify deliverability and does not consume credits. Returns a
+        ``CleanResult``. Pass ``options`` to control the cleaning behavior.
+        """
+        body: JSON = {"emails": list(emails)}
+        if options is not None:
+            body["options"] = options
+        return self._request("POST", "/api/v1/clean", body=body)
+
+    def extract(self, text: str, deduplicate: bool = True, lowercase: bool = True) -> JSON:
+        """Extract email addresses from arbitrary text or CSV content.
+
+        Returns an ``ExtractResult`` with the found addresses.
+        """
+        return self._request(
+            "POST",
+            "/api/v1/extract",
+            body={
+                "text": text,
+                "options": {"deduplicate": deduplicate, "lowercase": lowercase},
+            },
+        )
+
+    # ------------------------------------------------------------------ #
+    # Jobs
+    # ------------------------------------------------------------------ #
+    def jobs(
+        self,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> JSON:
+        """List bulk verification jobs (optionally filtered by status)."""
+        query: JSON = {}
+        if status is not None:
+            query["status"] = status
+        if limit is not None:
+            query["limit"] = limit
+        if offset is not None:
+            query["offset"] = offset
+        return self._request("GET", "/api/v1/jobs", query=query or None)
+
+    def job(self, job_id: str) -> JSON:
+        """Get the status of a single bulk job."""
+        return self._request("GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}")
+
+    def job_results(self, job_id: str) -> JSON:
+        """Get the per-email results of a completed bulk job as JSON."""
+        return self._request(
+            "GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}/results"
+        )
+
+    # ------------------------------------------------------------------ #
+    # Account, credits, usage
+    # ------------------------------------------------------------------ #
+    def account(self) -> JSON:
+        """Get the account profile and credit summary."""
+        return self._request("GET", "/api/v1/account")
+
+    def credits(self) -> JSON:
+        """Get the current credit balance."""
+        return self._request("GET", "/api/v1/credits")
+
+    def usage(self, period: Optional[str] = None, limit: Optional[int] = None) -> JSON:
+        """Get an API usage summary. ``period`` is one of day|week|month."""
+        query: JSON = {}
+        if period is not None:
+            query["period"] = period
+        if limit is not None:
+            query["limit"] = limit
+        return self._request("GET", "/api/v1/usage", query=query or None)
+
+    # ------------------------------------------------------------------ #
+    # Billing
+    # ------------------------------------------------------------------ #
+    def packages(self) -> JSON:
+        """List the available credit packages and their prices."""
+        return self._request(
+            "GET", "/api/v1/billing", query={"action": "packages"}
+        )
+
+    def payment_history(self) -> JSON:
+        """List the account's payment history."""
+        return self._request(
+            "GET", "/api/v1/billing", query={"action": "history"}
+        )
+
+    def buy_credits(
+        self,
+        package_id: str,
+        method: str = "stripe",
+        currency: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """Create a checkout to buy a credit package.
+
+        Args:
+            package_id: One of starter|basic|pro|business|enterprise.
+            method: ``stripe`` (default) or ``crypto``.
+            currency: Only for ``method="crypto"`` -- one of BTC|ETH|LTC|USDT|USDC.
+                When set, returns a raw wallet address + amount + qr_code.
+            idempotency_key: Passed through as the ``Idempotency-Key`` header.
+                Auto-generated if omitted so retries never double-charge.
+
+        Returns a Stripe or crypto checkout result.
+        """
+        body: JSON = {"package_id": package_id, "method": method}
+        if currency is not None:
+            body["currency"] = currency
+        return self._request(
+            "POST",
+            "/api/v1/billing",
+            body=body,
+            idempotency_key=idempotency_key or str(uuid.uuid4()),
+        )
+
+    # ------------------------------------------------------------------ #
+    # HTTP plumbing
+    # ------------------------------------------------------------------ #
+    def _request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[JSON] = None,
+        body: Optional[JSON] = None,
+        auth: bool = True,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        if auth:
+            if not self.api_key:
+                raise VeriflyError(
+                    "missing_api_key",
+                    "An API key is required for this call. "
+                    "Pass api_key to VeriflyClient(...).",
+                )
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        data: Optional[bytes] = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        # Only auto-retry requests that are safe to resend. GET/HEAD are
+        # idempotent; a POST is safe only when it carries an Idempotency-Key
+        # (the server dedupes those). Non-idempotent POSTs such as verify_batch
+        # have no server-side dedupe, so a timed-out request must never be
+        # re-sent or it could be charged 2-4x.
+        retryable = method in ("GET", "HEAD") or idempotency_key is not None
+
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                payload, status, resp_headers = self._send(method, url, headers, data)
+            except urllib.error.HTTPError as exc:
+                payload, status, resp_headers = self._read_http_error(exc)
+            except urllib.error.URLError as exc:
+                if retryable and attempt <= self.max_retries:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise VeriflyError(
+                    "http_error", f"Network error contacting Verifly: {exc.reason}"
+                ) from exc
+
+            request_id = resp_headers.get("x-request-id") or resp_headers.get(
+                "X-Request-Id"
+            )
+
+            if status == 429 or status >= 500:
+                if retryable and attempt <= self.max_retries:
+                    retry_after = self._parse_retry_after(resp_headers)
+                    time.sleep(
+                        retry_after if retry_after is not None else self._backoff(attempt)
+                    )
+                    continue
+
+            if status >= 400 or (isinstance(payload, dict) and payload.get("success") is False):
+                self._raise_for_envelope(payload, status, request_id)
+
+            if not isinstance(payload, dict):
+                raise VeriflyError(
+                    "invalid_response",
+                    "Expected a JSON object response from Verifly.",
+                    request_id,
+                    status,
+                )
+            return payload
+
+    def _send(self, method: str, url: str, headers: JSON, data: Optional[bytes]):
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        with self._opener.open(req, timeout=self.timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            parsed = json.loads(raw) if raw else {}
+            return parsed, resp.status, dict(resp.headers)
+
+    @staticmethod
+    def _read_http_error(exc: urllib.error.HTTPError):
+        raw = exc.read().decode("utf-8") if exc.fp else ""
+        try:
+            parsed = json.loads(raw) if raw else {}
+        except json.JSONDecodeError:
+            parsed = {"success": False, "error": {"code": "http_error", "message": raw or exc.reason}}
+        return parsed, exc.code, dict(exc.headers or {})
+
+    @staticmethod
+    def _raise_for_envelope(payload: Any, status: int, request_id: Optional[str]) -> None:
+        if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+            err = payload["error"]
+            raise VeriflyError(
+                err.get("code", "unknown_error"),
+                err.get("message", "Unknown error"),
+                request_id,
+                status,
+                err.get("suggestion"),
+            )
+        raise VeriflyError(
+            "http_error",
+            f"Request failed with HTTP {status}",
+            request_id,
+            status,
+        )
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return min(2.0 ** (attempt - 1), 30.0)
+
+    @staticmethod
+    def _parse_retry_after(headers: JSON) -> Optional[float]:
+        value = headers.get("Retry-After") or headers.get("retry-after")
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return None

verifly_email-1.0.0/verifly_email.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: verifly-email
+Version: 1.0.0
+Summary: Official Python SDK for the Verifly email-verification API (verifly.email)
+Author: Verifly
+License: MIT
+Project-URL: Homepage, https://verifly.email
+Project-URL: Documentation, https://verifly.email/docs/api
+Project-URL: API Spec, https://verifly.email/openapi.json
+Keywords: email,verification,validation,verifly,deliverability
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# verifly-email (Python)
+
+Official Python SDK for the [Verifly](https://verifly.email) email-verification API.
+
+> **Package naming.** Install **`verifly-email`** and import **`verifly_email`**.
+> The plain name `verifly` on PyPI belongs to an **unrelated 2FA company** — it
+> is *not* this project. Always use `verifly-email`.
+
+- Zero dependencies (pure Python standard library).
+- Fully typed, with docstrings on every method.
+- Built-in retry with backoff on `429` / `5xx` (honors `Retry-After`).
+- Automatic `Idempotency-Key` for `buy_credits` and `submit_bulk`.
+- Typed `VeriflyError(code, message, request_id)` on API error envelopes.
+
+## Install
+
+```bash
+pip install verifly-email          # once published
+# or, from this repo:
+pip install /path/to/sdks/python
+```
+
+## Quick start
+
+```python
+from verifly_email import VeriflyClient, VeriflyError
+
+client = VeriflyClient("vf_your_api_key")   # base_url defaults to https://verifly.email
+
+try:
+    r = client.verify("bill.gates@microsoft.com")
+    print(r["result"])           # deliverable | undeliverable | risky | unknown
+    print(r["recommendation"])   # safe_to_send | risky | do_not_send
+    print(r["credits"])          # {"used": 1, "remaining": 99}
+except VeriflyError as e:
+    print(e.code, e.message, e.request_id)
+```
+
+## Authentication
+
+Every call (except `register`) authenticates with your `vf_` key, sent as
+`Authorization: Bearer <api_key>`.
+
+```python
+client = VeriflyClient(api_key="vf_...", base_url="https://verifly.email")
+```
+
+## Create an account programmatically
+
+```python
+res = VeriflyClient.register("you@example.com", "a-strong-password")
+api_key = res["api_key"]["key"]   # shown ONCE — store it now
+client = VeriflyClient(api_key)
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `verify(email)` | Verify a single address. |
+| `verify_batch(emails, deduplicate=True, ...)` | Verify up to 100 addresses synchronously. |
+| `clean(emails, options=None)` | Clean/filter a list (no verification, no credits). |
+| `extract(text, deduplicate=True, lowercase=True)` | Pull email addresses out of text/CSV. |
+| `submit_bulk(emails=None, text=None, webhook_url=None, ...)` | Create an async bulk job (up to 1M). |
+| `jobs(status=None, limit=None, offset=None)` | List bulk jobs. |
+| `job(job_id)` | Get a bulk job's status. |
+| `job_results(job_id)` | Get a completed job's per-email results. |
+| `account()` | Account profile + credit summary. |
+| `credits()` | Current credit balance. |
+| `usage(period=None, limit=None)` | API usage summary (day/week/month). |
+| `packages()` | List credit packages and prices. |
+| `payment_history()` | List payment history. |
+| `buy_credits(package_id, method="stripe", currency=None)` | Create a Stripe/crypto checkout. |
+| `VeriflyClient.register(email, password)` *(classmethod)* | Self-register, returns account + API key. |
+
+### Examples
+
+```python
+# Batch (<=100), synchronous
+batch = client.verify_batch(
+    ["a@example.com", "b@example.com"],
+    exclude_role_accounts=True,
+)
+for item in batch["results"]:
+    print(item["email"], item["result"])
+
+# List hygiene without spending credits
+print(client.clean(["A@Example.com ", "a@example.com", "bad"])["..."])
+print(client.extract("contact us at sales@acme.io or ceo@acme.io"))
+
+# Async bulk + polling
+job = client.submit_bulk(emails=[...], webhook_url="https://you/webhook")
+status = client.job(job["job_id"] if "job_id" in job else job["job"]["id"])
+results = client.job_results(job_id)
+
+# Account / billing
+print(client.credits())
+print(client.packages())
+checkout = client.buy_credits("pro", method="stripe")
+checkout = client.buy_credits("pro", method="crypto", currency="USDT")
+```
+
+## Errors
+
+API error envelopes (`{"success": false, "error": {...}}`) and non-2xx
+responses raise `VeriflyError`:
+
+```python
+try:
+    client.verify("nope")
+except VeriflyError as e:
+    e.code         # e.g. "invalid_email", "insufficient_credits", "rate_limit_exceeded"
+    e.message
+    e.request_id   # from the x-request-id response header
+    e.status       # HTTP status
+    e.suggestion   # optional remediation hint
+```
+
+## Retries & idempotency
+
+- `429` and `5xx` responses are retried (default 3 times) with exponential
+  backoff, honoring the `Retry-After` header. Configure via
+  `VeriflyClient(..., max_retries=N, timeout=seconds)`.
+- `buy_credits` and `submit_bulk` send an `Idempotency-Key` header. One is
+  auto-generated per call; pass your own with `idempotency_key=...` to make a
+  specific retry safe end-to-end.
+
+## License
+
+MIT

verifly_email-1.0.0/verifly_email.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+verifly_email/__init__.py
+verifly_email/client.py
+verifly_email/py.typed
+verifly_email.egg-info/PKG-INFO
+verifly_email.egg-info/SOURCES.txt
+verifly_email.egg-info/dependency_links.txt
+verifly_email.egg-info/requires.txt
+verifly_email.egg-info/top_level.txt

verifly_email-1.0.0/verifly_email.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

verifly_email-1.0.0/verifly_email.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7

verifly_email-1.0.0/verifly_email.egg-info/top_level.txt

@@ -0,0 +1 @@
+verifly_email