mailroom-sdk 0.1.2
Python SDK for Mailroom Email Intelligence Platform
License: MIT
Requires Python: >=3.8

# Mailroom Python SDK

Python client library for the Mailroom Email Intelligence Platform.

## Installation

```bash
pip install mailroom
```

For additional features:
```bash
pip install mailroom[redis]    # Redis queue support
pip install mailroom[neo4j]    # Neo4j graph access
pip install mailroom[ml]       # ML utilities
```

## Quick Start

```python
from mailroom import Client

# Initialize client
client = Client(api_key="your-api-key")

# Search for deals
active_deals = client.deals.list_active()

# Get emails for a deal
deal = client.deals.get_with_details(
    deal_id="deal-123",
    include_events=True,
    include_emails=True
)

# Search companies
companies = client.companies.search("Acme Corp")
```

## Configuration

Set environment variables:
```bash
export MAILROOM_API_KEY="your-api-key"
export MAILROOM_BASE_URL="https://api.reasonal.ai"  # Optional
export MAILROOM_REDIS_URL="redis://localhost:6379"  # For queue features
```

Or configure programmatically:
```python
from mailroom import Client, Config

config = Config(
    api_key="your-api-key",
    base_url="https://api.reasonal.ai",
    redis_url="redis://localhost:6379",
    timeout=30.0,
    max_retries=3
)

client = Client(config=config)
```

## API Resources

### Deals
```python
# List active deals
deals = client.deals.list_active()

# Get deal with details
deal = client.deals.get_with_details(
    "deal-id",
    include_events=True,
    include_companies=True
)

# Add deal event
event = client.deals.add_event(
    "deal-id",
    event_type="ioi_received",
    actor_company_id="company-id",
    confidence=0.95,
    evidence_snippet="IOI received with proposed valuation..."
)

# Update deal stage
deal = client.deals.update_stage("deal-id", "due_diligence")
```

### Companies
```python
# Search companies
companies = client.companies.search("technology", company_type="strategic")

# Find by domain
company = client.companies.find_by_domain("acme.com")

# Get company people
people = client.companies.get_people("company-id", role="decision_maker")
```

### Emails
```python
# Search emails
emails = client.emails.search(
    query="merger proposal",
    deal_id="deal-id",
    has_attachments=True,
    since=datetime(2024, 1, 1)
)

# Get email thread
thread = client.emails.get_thread("email-id")
thread_emails = client.emails.get_thread_emails(thread.id)

# Batch operations
emails = client.emails.batch_get(
    ["email-1", "email-2", "email-3"],
    include=["thread", "deals"]
)
```

### People
```python
# Find person by email
person = client.people.find_by_email("john@acme.com")

# Search people
people = client.people.search("John", company_id="company-id")

# Update company association
person = client.people.update_company(
    "person-id",
    "new-company-id",
    job_title="Chief Technology Officer"
)
```

## Queue Operations (ML Team)

### Knowledge Graph Updates
```python
# Simple company enrichment
job_id = client.queues.kg_updates.enrich_company(
    company_id="company-123",
    properties={
        "industry": "SaaS",
        "employee_count": 150,
        "revenue_estimate": 25000000
    },
    confidence=0.92
)

# Batch enrichment
job_id = client.queues.kg_updates.enrich_companies_batch([
    {
        "company_id": "company-1",
        "properties": {"industry": "FinTech"}
    },
    {
        "company_id": "company-2",
        "properties": {"industry": "HealthTech"}
    }
])

# Create entities from extraction
job_id = client.queues.kg_updates.create_entities(
    entities=[
        {
            "type": "Company",
            "properties": {
                "name": "NewCo Inc",
                "domain": "newco.com"
            },
            "temporary_id": "temp-1"
        }
    ],
    process_name="email_entity_extraction",
    email_ids=["email-123"]
)
```

### Advanced KG Operations
```python
from mailroom.models import KgOperation, UpdateType

# Complex update with multiple operations
operations = [
    KgOperation.create_node(
        node_type="Person",
        properties={"name": "Jane Doe", "email": "jane@newco.com"},
        temporary_id="temp-person-1"
    ),
    KgOperation.create_relationship(
        from_node="temp-person-1",
        to_node="company-123",
        relationship_type="WORKS_AT",
        properties={"job_title": "CEO"}
    ),
    KgOperation.update_node(
        node_id="company-123",
        properties={"ceo_name": "Jane Doe"}
    )
]

job_id = client.queues.kg_updates.create_update(
    update_type=UpdateType.ENTITY_EXTRACTION,
    operations=operations,
    process_name="executive_extraction",
    email_ids=["email-456"]
)
```

### Modeling Queue
```python
# Queue email for AI processing
job_id = client.queues.modeling.queue_email_for_modeling(
    email_id="email-789",
    modeling_stages=["base", "sell_side_ma"],
    priority="high"
)

# Batch processing
job_ids = client.queues.modeling.queue_batch_modeling(
    email_ids=["email-1", "email-2", "email-3"],
    modeling_stages=["base"],
    priority="normal"
)

# Check job status
status = client.queues.modeling.get_status(job_id)

# Reprocess failed items
reprocessed = client.queues.modeling.reprocess_failed(limit=50)
```

### Queue Monitoring
```python
# Get all queue depths
status = client.queues.status()
print(status)
# {
#     "kg_updates": {"queue_depth": 42, "dlq_depth": 3},
#     "modeling": {"queue_depth": 156, "dlq_depth": 7}
# }

# Check specific queue
kg_depth = client.queues.kg_updates.queue_depth()
kg_dlq = client.queues.kg_updates.dlq_depth()
```

## Error Handling

```python
from mailroom import (
    MailroomError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError
)

try:
    deal = client.deals.get("invalid-id")
except NotFoundError as e:
    print(f"Deal not found: {e}")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after} seconds")
except MailroomError as e:
    print(f"API error: {e}")
```

## Advanced Usage

### Custom Request Options
```python
# With custom timeout
response = client.request(
    "GET",
    "/custom/endpoint",
    params={"filter": "active"},
    timeout=60.0
)

# Direct HTTP methods
data = client.get("/deals", params={"limit": 100})
result = client.post("/deals", json_data={"name": "New Deal"})
```

### Context Manager
```python
with Client(api_key="your-key") as client:
    deals = client.deals.list()
    # Client automatically closed
```

## Development

### Running Tests
```bash
pip install -e ".[dev]"
pytest
```

### Type Checking
```bash
mypy mailroom
```

### Code Formatting
```bash
black mailroom
ruff mailroom
```

## License

MIT License - see LICENSE file for details.