> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> gork-sdk — the same email surface in snake_case, plus agent tools.

```bash theme={null}
pip install gork-sdk
```

## Client

```python theme={null}
import os
from gork import Gork, GorkError

gork = Gork(api_key=os.environ["GORK_API_KEY"])  # falls back to GORK_KEY, then GORK_API_KEY
# gork = Gork(api_key="gork_live_...", base_url="https://api.gork.email")
```

## Inboxes

```python theme={null}
inbox = gork.create_inbox(username="sdr-alex", name="SDR Agent")
inboxes = gork.list_inboxes()
one = gork.get_inbox("inb_123")
gork.delete_inbox("inb_123")
```

## Messages & search

```python theme={null}
msg = gork.send_message(
    inbox_id="inb_123",
    to=["prospect@example.com"],
    subject="Quick question",
    text="Hi — got 10 minutes Thursday?",
)

# Idempotent send (safe retries)
gork.send_message(
    inbox_id="inb_123", to=["a@example.com"],
    subject="Hi", text="Hello", idempotency_key="campaign-1-user-42",
)

recent = gork.list_messages(inbox_id="inb_123", limit=20)
hits = gork.search_messages("invoice", direction="inbound")
full = gork.get_message("msg_123")
gork.cancel_scheduled("msg_123")  # scheduled sends only
```

Threaded reply via `in_reply_to`, attachments as base64 dicts (max 10 files, 10MB each, 15MB total):

```python theme={null}
gork.send_message(
    inbox_id="inb_123", to=["prospect@example.com"],
    subject="Re: Quick question", text="Bumping this up.",
    in_reply_to="msg_original",
    attachments=[{"filename": "one-pager.pdf", "contentType": "application/pdf", "content": "<base64>"}],
)
```

## Threads & attachments

```python theme={null}
threads = gork.list_threads()
thread = gork.get_thread("thd_123")

pdf_bytes: bytes = gork.download_attachment("att_123")
```

## Drafts

```python theme={null}
draft = gork.create_draft(inbox_id="inb_123", to=["a@example.com"], subject="Hi")
gork.update_draft(draft["id"], text="Hello — final copy.")
gork.send_draft(draft["id"])  # idempotent per draft
open_drafts = gork.list_drafts(status="draft")
gork.discard_draft(draft["id"])
```

## Domains, suppressions, keys, webhooks

```python theme={null}
domain = gork.create_domain("mail.example.com")
gork.verify_domain(domain["id"])
gork.list_domains()
gork.delete_domain(domain["id"])

gork.suppress("bad@example.com", reason="manual")
gork.list_suppressions()
gork.unsuppress("sup_123")

gork.create_api_key("agent-01")
gork.list_api_keys()
gork.revoke_api_key("key_123")

gork.create_webhook("https://example.com/hooks/gork")
gork.list_webhooks()
gork.rotate_webhook_secret("wh_123")
gork.delete_webhook("wh_123")
```

Verify the `X-Gork-Signature` header (`t=<unix>,v1=<hex>`, ±300s tolerance):

```python theme={null}
from gork.client import verify_signature

ok = verify_signature(raw_body, signature_header, secret)
```

## Agent tools

Function-calling schemas for OpenAI / Anthropic / LangChain-compatible loops:

```python theme={null}
tools = gork.get_tools()
result = gork.execute_tool("gork_send_email", {
    "inbox_id": "inb_123", "to": ["a@example.com"],
    "subject": "Hi", "text": "Hello",
})
```

## Errors

```python theme={null}
from gork import GorkError

try:
    gork.send_message(inbox_id="inb_123", to=["a@example.com"], subject="Hi", text="Hello")
except GorkError as e:
    print(e.code, e.status, e)  # e.details for field errors
```