emailsherlock-sdk 0.1.0__tar.gz

emailsherlock_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.8', '3.9', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '${{ matrix.python }}' }
+      - run: pip install pytest
+      - run: pytest -q

emailsherlock_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.11' }
+      - run: pip install build pytest
+      - run: pytest -q
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

emailsherlock_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.venv/

emailsherlock_sdk-0.1.0/LICENSE

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

emailsherlock_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: emailsherlock-sdk
+Version: 0.1.0
+Summary: Official Python client for the EmailSherlock email-verification API.
+Project-URL: Homepage, https://emailsherlock.com
+Project-URL: Documentation, https://emailsherlock.com/api/docs
+Project-URL: Source, https://github.com/Emailsherlock1/python
+Author: EmailSherlock
+License: MIT
+License-File: LICENSE
+Keywords: disposable,email,email-validation,email-verification,emailsherlock,mx,smtp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# emailsherlock-sdk
+
+Official Python client for the [EmailSherlock](https://emailsherlock.com) email-verification API. Verify one address or a batch over HTTPS with an API key.
+
+Zero third-party dependencies (uses only the standard library). Python 3.8+.
+
+## Install
+
+```bash
+pip install emailsherlock-sdk
+```
+
+The distribution is `emailsherlock-sdk`; the import is `emailsherlock`:
+
+```python
+from emailsherlock import Emailsherlock
+```
+
+## Quick start
+
+```python
+import os
+from emailsherlock import Emailsherlock
+
+# reads the key from the environment, never hard-code it
+es = Emailsherlock(api_key=os.environ["ES_KEY"])
+
+result = es.verify.single(email="jane@acme.com")
+
+print(result.result)  # "valid"
+print(result.score)   # 0.95
+```
+
+Called with no argument, `Emailsherlock()` reads `ES_KEY` (or
+`EMAILSHERLOCK_API_KEY`) from the environment.
+
+## Batch
+
+Up to 100 addresses per call:
+
+```python
+batch = es.verify.batch(emails=["jane@acme.com", "sales@acme.com"])
+
+for item in batch.results:
+    if isinstance(item, VerifyResult):
+        print(item.email, item.result)
+    else:  # BatchItemError
+        print(item.email, "failed:", item.error)
+```
+
+## The result object
+
+`VerifyResult` mirrors the API JSON:
+
+| attribute    | type  | meaning                                                         |
+|--------------|-------|-----------------------------------------------------------------|
+| `email`      | str   | the address you sent                                            |
+| `result`     | str   | `valid` · `invalid` · `catch_all` · `disposable` · `role` · `unknown` |
+| `mx`         | bool  | the domain has reachable MX records                             |
+| `disposable` | bool  | throwaway / temporary-mail provider                             |
+| `role`       | bool  | role address such as `info@` or `sales@`                        |
+| `catch_all`  | bool  | host accepts mail for any local part                            |
+| `score`      | float | 0–1 confidence, higher is safer to send to                      |
+| `freshness`  | str   | `fresh` · `cached_recent` · `cached_stale_refreshed`            |
+
+## Credits and rate limits
+
+After every call:
+
+```python
+es.credits_remaining   # e.g. 41
+es.rate_limit          # {"limit": 60, "remaining": 59, "reset": 1700000000}
+```
+
+## Errors
+
+Every failure raises a subclass of `EmailsherlockError`:
+
+| class                       | HTTP | when                                          |
+|-----------------------------|------|-----------------------------------------------|
+| `AuthenticationError`       | 401  | missing or invalid API key                    |
+| `ForbiddenError`            | 403  | key lacks the endpoint's scope (`required_scope`) |
+| `InsufficientCreditsError`  | 402  | not enough credits (`credits_required`, `credits_remaining`) |
+| `RateLimitError`            | 429  | rate limit hit (`retry_after`, `limit`, `remaining`, `reset`) |
+| `ValidationError`           | 400 / 422 | the request body was rejected            |
+| `ServiceUnavailableError`   | 503  | verify engine unavailable (the credit is auto-refunded) |
+
+```python
+from emailsherlock import RateLimitError
+
+try:
+    es.verify.single(email="jane@acme.com")
+except RateLimitError as err:
+    print(f"retry after {err.retry_after}s")
+```
+
+## License
+
+MIT. Full API reference: https://emailsherlock.com/api/docs

emailsherlock_sdk-0.1.0/README.md

@@ -0,0 +1,99 @@
+# emailsherlock-sdk
+
+Official Python client for the [EmailSherlock](https://emailsherlock.com) email-verification API. Verify one address or a batch over HTTPS with an API key.
+
+Zero third-party dependencies (uses only the standard library). Python 3.8+.
+
+## Install
+
+```bash
+pip install emailsherlock-sdk
+```
+
+The distribution is `emailsherlock-sdk`; the import is `emailsherlock`:
+
+```python
+from emailsherlock import Emailsherlock
+```
+
+## Quick start
+
+```python
+import os
+from emailsherlock import Emailsherlock
+
+# reads the key from the environment, never hard-code it
+es = Emailsherlock(api_key=os.environ["ES_KEY"])
+
+result = es.verify.single(email="jane@acme.com")
+
+print(result.result)  # "valid"
+print(result.score)   # 0.95
+```
+
+Called with no argument, `Emailsherlock()` reads `ES_KEY` (or
+`EMAILSHERLOCK_API_KEY`) from the environment.
+
+## Batch
+
+Up to 100 addresses per call:
+
+```python
+batch = es.verify.batch(emails=["jane@acme.com", "sales@acme.com"])
+
+for item in batch.results:
+    if isinstance(item, VerifyResult):
+        print(item.email, item.result)
+    else:  # BatchItemError
+        print(item.email, "failed:", item.error)
+```
+
+## The result object
+
+`VerifyResult` mirrors the API JSON:
+
+| attribute    | type  | meaning                                                         |
+|--------------|-------|-----------------------------------------------------------------|
+| `email`      | str   | the address you sent                                            |
+| `result`     | str   | `valid` · `invalid` · `catch_all` · `disposable` · `role` · `unknown` |
+| `mx`         | bool  | the domain has reachable MX records                             |
+| `disposable` | bool  | throwaway / temporary-mail provider                             |
+| `role`       | bool  | role address such as `info@` or `sales@`                        |
+| `catch_all`  | bool  | host accepts mail for any local part                            |
+| `score`      | float | 0–1 confidence, higher is safer to send to                      |
+| `freshness`  | str   | `fresh` · `cached_recent` · `cached_stale_refreshed`            |
+
+## Credits and rate limits
+
+After every call:
+
+```python
+es.credits_remaining   # e.g. 41
+es.rate_limit          # {"limit": 60, "remaining": 59, "reset": 1700000000}
+```
+
+## Errors
+
+Every failure raises a subclass of `EmailsherlockError`:
+
+| class                       | HTTP | when                                          |
+|-----------------------------|------|-----------------------------------------------|
+| `AuthenticationError`       | 401  | missing or invalid API key                    |
+| `ForbiddenError`            | 403  | key lacks the endpoint's scope (`required_scope`) |
+| `InsufficientCreditsError`  | 402  | not enough credits (`credits_required`, `credits_remaining`) |
+| `RateLimitError`            | 429  | rate limit hit (`retry_after`, `limit`, `remaining`, `reset`) |
+| `ValidationError`           | 400 / 422 | the request body was rejected            |
+| `ServiceUnavailableError`   | 503  | verify engine unavailable (the credit is auto-refunded) |
+
+```python
+from emailsherlock import RateLimitError
+
+try:
+    es.verify.single(email="jane@acme.com")
+except RateLimitError as err:
+    print(f"retry after {err.retry_after}s")
+```
+
+## License
+
+MIT. Full API reference: https://emailsherlock.com/api/docs

emailsherlock_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "emailsherlock-sdk"
+version = "0.1.0"
+description = "Official Python client for the EmailSherlock email-verification API."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "EmailSherlock" }]
+keywords = ["email", "email-verification", "email-validation", "emailsherlock", "mx", "smtp", "disposable"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Email",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://emailsherlock.com"
+Documentation = "https://emailsherlock.com/api/docs"
+Source = "https://github.com/Emailsherlock1/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/emailsherlock"]

emailsherlock_sdk-0.1.0/src/emailsherlock/__init__.py

@@ -0,0 +1,28 @@
+"""Official Python client for the EmailSherlock email-verification API."""
+from ._version import __version__
+from .client import Emailsherlock
+from .errors import (
+    AuthenticationError,
+    EmailsherlockError,
+    ForbiddenError,
+    InsufficientCreditsError,
+    RateLimitError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import BatchItemError, BatchResponse, VerifyResult
+
+__all__ = [
+    "__version__",
+    "Emailsherlock",
+    "VerifyResult",
+    "BatchResponse",
+    "BatchItemError",
+    "EmailsherlockError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "ValidationError",
+    "ServiceUnavailableError",
+]

emailsherlock_sdk-0.1.0/src/emailsherlock/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

emailsherlock_sdk-0.1.0/src/emailsherlock/client.py

@@ -0,0 +1,133 @@
+"""HTTP client for the EmailSherlock verify API. Zero third-party dependencies."""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from ._version import __version__
+from .errors import EmailsherlockError, error_from_response
+from .models import BatchResponse, VerifyResult
+
+DEFAULT_BASE_URL = "https://api.emailsherlock.com"
+
+
+def _num(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class _VerifyResource:
+    """Verify-endpoint methods, reached as ``client.verify``."""
+
+    def __init__(self, client: "Emailsherlock") -> None:
+        self._client = client
+
+    def single(self, email: str) -> VerifyResult:
+        """Verify a single address."""
+        data = self._client._request("/v1/verify/single", {"email": email})
+        return VerifyResult.from_dict(data)
+
+    def batch(self, emails: List[str]) -> BatchResponse:
+        """Verify up to 100 addresses in one call."""
+        data = self._client._request("/v1/verify/batch", {"emails": list(emails)})
+        return BatchResponse.from_dict(data)
+
+
+class Emailsherlock:
+    """Client for the EmailSherlock verify API.
+
+    The API key is read from ``api_key`` or, if omitted, from the ``ES_KEY`` /
+    ``EMAILSHERLOCK_API_KEY`` environment variables.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.environ.get("ES_KEY") or os.environ.get("EMAILSHERLOCK_API_KEY")
+        if not key:
+            raise EmailsherlockError(
+                "No API key provided. Pass api_key= or set ES_KEY.",
+                code="config_error",
+            )
+        self._api_key = key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+        #: credits left after the most recent request (X-Credits-Remaining)
+        self.credits_remaining: Optional[float] = None
+        #: rate-limit window after the most recent request (X-RateLimit-*)
+        self.rate_limit: Dict[str, Optional[float]] = {
+            "limit": None,
+            "remaining": None,
+            "reset": None,
+        }
+
+        self.verify = _VerifyResource(self)
+
+    def _request(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        url = self._base_url + path
+        body = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            url,
+            data=body,
+            method="POST",
+            headers={
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "emailsherlock-python/{}".format(__version__),
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                raw = response.read().decode("utf-8")
+                self._capture_meta(response.headers)
+                status = response.status
+                headers = response.headers
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8")
+            self._capture_meta(exc.headers)
+            parsed = self._parse(raw)
+            raise error_from_response(exc.code, parsed, exc.headers)
+        except urllib.error.URLError as exc:
+            raise EmailsherlockError(
+                "Request to {} failed: {}".format(path, exc.reason),
+                code="network_error",
+            )
+
+        parsed = self._parse(raw)
+        if status >= 400:
+            raise error_from_response(status, parsed, headers)
+        return parsed if isinstance(parsed, dict) else {}
+
+    def _capture_meta(self, headers: Any) -> None:
+        credits = headers.get("X-Credits-Remaining")
+        if credits is not None:
+            self.credits_remaining = _num(credits)
+        if headers.get("X-RateLimit-Limit") is not None:
+            self.rate_limit = {
+                "limit": _num(headers.get("X-RateLimit-Limit")),
+                "remaining": _num(headers.get("X-RateLimit-Remaining")),
+                "reset": _num(headers.get("X-RateLimit-Reset")),
+            }
+
+    @staticmethod
+    def _parse(raw: str) -> Optional[Dict[str, Any]]:
+        if not raw:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            return None

emailsherlock_sdk-0.1.0/src/emailsherlock/errors.py

@@ -0,0 +1,125 @@
+"""Exception hierarchy. Every failure raises a subclass of EmailsherlockError."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+def _num(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class EmailsherlockError(Exception):
+    """Base class for every error this client raises."""
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+
+class AuthenticationError(EmailsherlockError):
+    """401 - missing or invalid API key."""
+
+
+class ForbiddenError(EmailsherlockError):
+    """403 - the key lacks the scope this endpoint needs."""
+
+    def __init__(self, *args: Any, required_scope: Optional[str] = None, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self.required_scope = required_scope
+
+
+class InsufficientCreditsError(EmailsherlockError):
+    """402 - not enough credits on the wallet for this request."""
+
+    def __init__(
+        self,
+        *args: Any,
+        credits_required: Optional[float] = None,
+        credits_remaining: Optional[float] = None,
+        **kw: Any,
+    ) -> None:
+        super().__init__(*args, **kw)
+        self.credits_required = credits_required
+        self.credits_remaining = credits_remaining
+
+
+class RateLimitError(EmailsherlockError):
+    """429 - per-key sliding-window rate limit hit."""
+
+    def __init__(
+        self,
+        *args: Any,
+        retry_after: Optional[float] = None,
+        limit: Optional[float] = None,
+        remaining: Optional[float] = None,
+        reset: Optional[float] = None,
+        **kw: Any,
+    ) -> None:
+        super().__init__(*args, **kw)
+        self.retry_after = retry_after
+        self.limit = limit
+        self.remaining = remaining
+        self.reset = reset
+
+
+class ValidationError(EmailsherlockError):
+    """400 / 422 - the request body was rejected."""
+
+
+class ServiceUnavailableError(EmailsherlockError):
+    """503 - the verify engine could not answer; the credit was auto-refunded."""
+
+
+def error_from_response(
+    status: int,
+    body: Optional[Dict[str, Any]],
+    headers: Any,
+) -> EmailsherlockError:
+    envelope = (body or {}).get("error", {}) if isinstance(body, dict) else {}
+    code = envelope.get("code")
+    message = envelope.get("message") or "HTTP {}".format(status)
+
+    if status == 401:
+        return AuthenticationError(message, status=status, code=code)
+    if status == 403:
+        return ForbiddenError(
+            message,
+            status=status,
+            code=code,
+            required_scope=envelope.get("required_scope") or headers.get("X-Required-Scope"),
+        )
+    if status == 402:
+        return InsufficientCreditsError(
+            message,
+            status=status,
+            code=code,
+            credits_required=_num(headers.get("X-Credits-Required")),
+            credits_remaining=_num(headers.get("X-Credits-Remaining")),
+        )
+    if status == 429:
+        return RateLimitError(
+            message,
+            status=status,
+            code=code,
+            retry_after=_num(headers.get("Retry-After")),
+            limit=_num(headers.get("X-RateLimit-Limit")),
+            remaining=_num(headers.get("X-RateLimit-Remaining")),
+            reset=_num(headers.get("X-RateLimit-Reset")),
+        )
+    if status in (400, 422):
+        return ValidationError(message, status=status, code=code)
+    if status == 503:
+        return ServiceUnavailableError(message, status=status, code=code)
+    return EmailsherlockError(message, status=status, code=code)

emailsherlock_sdk-0.1.0/src/emailsherlock/models.py

@@ -0,0 +1,66 @@
+"""Typed result objects returned by the client."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class VerifyResult:
+    """The result for one verified address. Mirrors the API JSON."""
+
+    email: str
+    result: str  # valid | invalid | catch_all | disposable | role | unknown
+    mx: bool
+    disposable: bool
+    role: bool
+    catch_all: bool
+    score: float
+    freshness: str  # fresh | cached_recent | cached_stale_refreshed
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "VerifyResult":
+        return cls(
+            email=data.get("email", ""),
+            result=data.get("result", "unknown"),
+            mx=bool(data.get("mx", False)),
+            disposable=bool(data.get("disposable", False)),
+            role=bool(data.get("role", False)),
+            catch_all=bool(data.get("catch_all", False)),
+            score=float(data.get("score", 0.0)),
+            freshness=data.get("freshness", ""),
+            raw=data,
+        )
+
+
+@dataclass
+class BatchItemError:
+    """A per-address failure inside a batch response."""
+
+    email: Optional[str]
+    error: str  # invalid_email | insufficient_credits | verify_unavailable
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchItemError":
+        return cls(email=data.get("email"), error=data.get("error", "unknown"))
+
+
+BatchItem = Union[VerifyResult, BatchItemError]
+
+
+@dataclass
+class BatchResponse:
+    """The response of a batch call: a list of results and/or per-item errors."""
+
+    results: List[BatchItem]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BatchResponse":
+        items: List[BatchItem] = []
+        for item in data.get("results", []):
+            if isinstance(item, dict) and "error" in item:
+                items.append(BatchItemError.from_dict(item))
+            else:
+                items.append(VerifyResult.from_dict(item))
+        return cls(results=items)

emailsherlock_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,125 @@
+"""Unit tests with a stubbed urlopen. No network."""
+import io
+import json
+import sys
+import urllib.error
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import emailsherlock
+from emailsherlock import (
+    AuthenticationError,
+    Emailsherlock,
+    InsufficientCreditsError,
+    RateLimitError,
+    VerifyResult,
+    BatchItemError,
+)
+
+
+class FakeHeaders(dict):
+    def get(self, key, default=None):
+        for k, v in self.items():
+            if k.lower() == key.lower():
+                return v
+        return default
+
+
+class FakeResponse:
+    def __init__(self, status, body, headers):
+        self.status = status
+        self._body = json.dumps(body).encode()
+        self.headers = FakeHeaders(headers)
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def patch(monkeypatch, status, body, headers=None):
+    headers = headers or {}
+    if status >= 400:
+        def raiser(req, timeout=None):
+            raise urllib.error.HTTPError(
+                req.full_url, status, "err", FakeHeaders(headers),
+                io.BytesIO(json.dumps(body).encode()),
+            )
+        monkeypatch.setattr(emailsherlock.client.urllib.request, "urlopen", raiser)
+    else:
+        monkeypatch.setattr(
+            emailsherlock.client.urllib.request,
+            "urlopen",
+            lambda req, timeout=None: FakeResponse(status, body, headers),
+        )
+
+
+def test_single_ok(monkeypatch):
+    patch(
+        monkeypatch, 200,
+        {"email": "jane@acme.com", "result": "valid", "mx": True, "disposable": False,
+         "role": False, "catch_all": False, "score": 0.95, "freshness": "fresh"},
+        {"X-Credits-Remaining": "41", "X-RateLimit-Limit": "60", "X-RateLimit-Remaining": "59", "X-RateLimit-Reset": "1700000000"},
+    )
+    es = Emailsherlock("k")
+    result = es.verify.single("jane@acme.com")
+    assert isinstance(result, VerifyResult)
+    assert result.result == "valid"
+    assert result.score == 0.95
+    assert es.credits_remaining == 41
+    assert es.rate_limit["limit"] == 60
+
+
+def test_batch_mixed(monkeypatch):
+    patch(monkeypatch, 200, {"results": [
+        {"email": "jane@acme.com", "result": "valid", "mx": True, "disposable": False, "role": False, "catch_all": False, "score": 0.9, "freshness": "fresh"},
+        {"email": "nope@", "error": "invalid_email"},
+    ]})
+    es = Emailsherlock("k")
+    batch = es.verify.batch(["jane@acme.com", "nope@"])
+    assert len(batch.results) == 2
+    assert isinstance(batch.results[0], VerifyResult)
+    assert isinstance(batch.results[1], BatchItemError)
+    assert batch.results[1].error == "invalid_email"
+
+
+def test_401(monkeypatch):
+    patch(monkeypatch, 401, {"error": {"code": "unauthorized", "message": "Invalid API key."}})
+    es = Emailsherlock("bad")
+    with pytest.raises(AuthenticationError) as exc:
+        es.verify.single("a@b.com")
+    assert exc.value.status == 401
+    assert exc.value.code == "unauthorized"
+
+
+def test_402(monkeypatch):
+    patch(monkeypatch, 402, {"error": {"code": "insufficient_credits", "message": "Not enough."}},
+          {"X-Credits-Required": "1", "X-Credits-Remaining": "0"})
+    es = Emailsherlock("k")
+    with pytest.raises(InsufficientCreditsError) as exc:
+        es.verify.single("a@b.com")
+    assert exc.value.credits_required == 1
+    assert exc.value.credits_remaining == 0
+
+
+def test_429(monkeypatch):
+    patch(monkeypatch, 429, {"error": {"code": "rate_limit_exceeded", "message": "Slow down."}},
+          {"Retry-After": "30"})
+    es = Emailsherlock("k")
+    with pytest.raises(RateLimitError) as exc:
+        es.verify.single("a@b.com")
+    assert exc.value.retry_after == 30
+
+
+def test_missing_key(monkeypatch):
+    monkeypatch.delenv("ES_KEY", raising=False)
+    monkeypatch.delenv("EMAILSHERLOCK_API_KEY", raising=False)
+    with pytest.raises(emailsherlock.EmailsherlockError):
+        Emailsherlock()