encrata 0.3.0

Python bindings for the Encrata email intelligence API

Encrata Python Library

The Encrata Python library provides convenient access to the Encrata API from applications written in Python. Look up any person by their email address — get their name, company, job title, social profiles, breach history, and more.

API Documentation

See the Encrata API docs.

Installation

pip install encrata

Requirements

• Python 3.9+
• httpx (installed automatically)

Usage

The library needs to be configured with your account's API key, available in your Encrata Dashboard.

from encrata import Encrata

client = Encrata("enc_live_...")

The client keeps a pooled HTTP connection open. Reuse a single instance for the lifetime of your application, or use it as a context manager to close the pool automatically:

with Encrata("enc_live_...") as client:
    person = client.lookup("[e-mail]")

Look up a person by email

person = client.lookup("[e-mail]")

print(person.name)        # "Elon Musk"
print(person.company)     # "Tesla"
print(person.role)        # "CEO"
print(person.location)    # "Austin, Texas"
print(person.validity)    # "valid"

Each lookup costs 1 credit. Cached results within 24 hours are served from cache.

Select specific fields

Only return the fields you need to minimize response size:

person = client.lookup("[e-mail]", fields=["name", "company", "role", "socials"])

print(person.name)             # "Satya Nadella"
print(person.socials.linkedin) # "https://linkedin.com/in/satyanadella"

Available fields: name, email, company, role, industry, location, bio, age, gender, education, phone, photo, validity, socials, breaches, registered_services, news, publications.

Validate an email address (free)

Check if an email is deliverable without using any credits:

result = client.validate("[e-mail]")

print(result.validity)  # "valid", "invalid", "disposable", or "unknown"
print(result.message)   # "Email is deliverable and valid."

Check data breaches (free)

See if an email has been exposed in known data breaches:

report = client.breaches("[e-mail]")

print(report.count)         # 3
print(report.services)      # ["Adobe", "LinkedIn", "Dropbox"]
print(report.exposed_data)  # ["email", "password", "username"]

Monitoring

Set up monitors to track changes in email intelligence over time. When a person changes jobs, gets a new title, or appears in a breach — you'll know.

Create a monitor

monitor = client.create_monitor(
    "Sales Leads",
    emails=["[e-mail]", "[e-mail]"],
    frequency="weekly",
)

print(monitor.id)           # "mon_abc123..."
print(monitor.email_count)  # 2

List monitors

monitors = client.list_monitors()
for m in monitors:
    print(f"{m.name}: {m.email_count} emails, {m.status}")

Trigger a run

result = client.trigger_run(monitor.id)
print(result["run_id"])   # "run_xyz789..."
print(result["status"])   # "running"

Get run results

runs, total = client.list_runs(monitor.id)
for run in runs:
    print(f"Run {run.id}: {run.changes_detected} changes")

# Get detailed results for a run
snapshots, total = client.get_run_results(monitor.id, runs[0].id, changes_only=True)
for snap in snapshots:
    print(f"{snap.email}: changes={snap.changes}")

List all runs across monitors

all_runs, total = client.list_all_runs(limit=10)
all_results, total = client.list_all_results(changes_only=True)

Contact Lists

Manage reusable email lists that can be used as data sources for monitors.

Create a contact list

contact_list = client.create_contact_list(
    "Engineering Team",
    emails=["[e-mail]", "[e-mail]"],
)
print(contact_list.id)

Manage list emails

# List all contact lists
lists = client.list_contact_lists()

# Add emails
client.add_contact_list_emails(contact_list.id, ["[e-mail]"])

# List emails in a list
emails = client.list_contact_list_emails(contact_list.id)

# Remove emails
client.delete_contact_list_emails(contact_list.id, ["[e-mail]"])

# Delete the list
client.delete_contact_list(contact_list.id)

Use a list as a monitor source

monitor = client.create_monitor("Team Monitor", list_id=contact_list.id)

Handling exceptions

from encrata import Encrata, AuthenticationError, InsufficientCreditsError

client = Encrata("enc_live_...")

try:
    person = client.lookup("[e-mail]")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("No credits remaining — top up at encrata.com/settings/billing")

Exception	Cause
AuthenticationError	Invalid or missing API key
InsufficientCreditsError	Account has 0 credits remaining
InvalidRequestError	Malformed request (e.g. invalid email)
RateLimitError	Too many requests
APIConnectionError	Network connectivity issue
APIError	Unexpected server error

Configuration options

client = Encrata(
    "enc_live_...",
    base_url="https://api.encrata.com",  # default
    timeout=30,                           # request timeout in seconds
    max_retries=3,                        # retries for transient failures
)

Transient failures (HTTP 429, 500, 502, 503, 504, timeouts, and connection errors) are retried automatically using exponential backoff with full jitter. A Retry-After response header is honored and capped at 30 seconds.

Force fresh lookup

Bypass the 24-hour cache to get the latest data:

person = client.lookup("[e-mail]", nocache=True)

Async

An async client, AsyncEncrata, exposes the same methods with async/await. It shares one connection pool and can run many lookups concurrently

import asyncio
from encrata import AsyncEncrata

async def main():
    async with AsyncEncrata("enc_live_...") as client:
        person = await client.lookup("[e-mail]")
        print(person.name)

        # Run many lookups concurrently (bounded by max_concurrency):
        people = await client.lookup_many([
            "[e-mail]",
            "[e-mail]",
            "[e-mail]",
        ])
        for p in people:
            print(p.name)

asyncio.run(main())

MCP (Model Context Protocol)

Encrata also provides an MCP server for AI agent frameworks like Claude, Cursor, and Windsurf. Add this to your MCP configuration:

{
  "mcpServers": {
    "encrata": {
      "url": "https://api.encrata.com/mcp",
      "headers": {
        "Authorization": "Bearer enc_live_..."
      }
    }
  }
}

Support

• Documentation: docs.encrata.com
• Dashboard: encrata.com
• Email: [e-mail]

License

MIT