hunter-sdk

Python SDK for the Hunter.io v2 REST API. Provides email verification, domain search, and email finding with an optional in-memory caching layer.

Requirements

• Python 3.11+
• requests >= 2.31.0

Installation

pip install hunter-sdk

Or with Hatch:

hatch shell

Quick Start

Low-level client

from hunter import HunterClient

client = HunterClient(api_key="your_api_key")

# Verify an email address
result = client.verify_email("someone@example.com")

# Find all emails for a domain
result = client.search_domain("example.com")

# Find the most likely email for a person
result = client.find_email("example.com", "Jane", "Doe")

Service layer with caching

HunterService wraps HunterClient and HunterStorage to provide read-through in-memory caching. Repeated calls with the same arguments skip the API and return the stored result.

from hunter import HunterClient, HunterService, HunterStorage

client = HunterClient(api_key="your_api_key")
storage = HunterStorage()
service = HunterService(client=client, storage=storage)

# First call hits the API and caches the result
result = service.verify_email("someone@example.com")

# Second call returns from cache — no API request made
result = service.verify_email("someone@example.com")

API Reference

HunterClient(api_key, timeout=10)

Thin HTTP wrapper around Hunter.io v2.

Method	Parameters	Returns
verify_email(email)	email: str	VerifyResponseDict
search_domain(domain)	domain: str	DomainSearchResponseDict
find_email(domain, first_name, last_name)	domain, first_name, last_name: str	FindResponseDict

HunterService(client, storage)

Orchestrates HunterClient + HunterStorage with read-through caching. Same three methods as HunterClient.

HunterStorage()

In-memory key-value store for API responses. CRUD methods: create(), get(), update(), delete(), list_keys().

Error Handling

All exceptions inherit from HunterError.

from hunter import (
    HunterAuthError,        # 401 — invalid or missing API key
    HunterNotFoundError,    # 404 — resource not found
    HunterRateLimitError,   # 429 — rate limit or quota exceeded
    HunterAPIError,         # other HTTP errors (has .status_code)
    HunterNetworkError,     # connection / timeout failure
)

try:
    result = client.verify_email("someone@example.com")
except HunterAuthError:
    print("Invalid API key")
except HunterRateLimitError:
    print("Rate limit hit — back off and retry")
except HunterNetworkError:
    print("Network failure")
except HunterAPIError as exc:
    print(f"API error {exc.status_code}")

Development

# Install dev dependencies
pip install -e ".[dev]"
# or
hatch shell

# Run tests
pytest

# Run tests with coverage
pytest --cov=hunter

# Type check
mypy hunter

# Lint
flake8 hunter tests

License

MIT