gork-sdk 0.1.0__tar.gz

gork_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: gork-sdk
+Version: 0.1.0
+Summary: Official Python SDK for gork.email programmable email infrastructure for AI agents
+Author: gork.email
+License: MIT
+Project-URL: Homepage, https://gork.email
+Project-URL: Documentation, https://gork.email/docs
+Project-URL: Repository, https://github.com/shyamcxy/gork-sdk-python
+Project-URL: Issues, https://github.com/shyamcxy/gork-sdk-python/issues
+Keywords: email,agent,ai,mcp,inbox,mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gork-sdk — Python SDK for gork.email
+
+> **Pre-alpha (0.1.0).** gork.email is in active development and the API may change between 0.x releases without a major bump. Pin an exact version in production.
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and
+receive mail, search a mailbox, compose drafts, schedule sends, read
+attachments, and manage threads, webhooks, domains, keys, and suppressions.
+
+This SDK tracks the REST API at `https://api.gork.email/v1` and the TypeScript
+SDK (`@gork/sdk`); the method names and parameters match.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@try.gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-0.1.0/README.md

@@ -0,0 +1,49 @@
+# gork-sdk — Python SDK for gork.email
+
+> **Pre-alpha (0.1.0).** gork.email is in active development and the API may change between 0.x releases without a major bump. Pin an exact version in production.
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and
+receive mail, search a mailbox, compose drafts, schedule sends, read
+attachments, and manage threads, webhooks, domains, keys, and suppressions.
+
+This SDK tracks the REST API at `https://api.gork.email/v1` and the TypeScript
+SDK (`@gork/sdk`); the method names and parameters match.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@try.gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gork-sdk"
+version = "0.1.0"
+description = "Official Python SDK for gork.email programmable email infrastructure for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "gork.email" }]
+keywords = ["email", "agent", "ai", "mcp", "inbox", "mail"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Communications :: Email",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://gork.email"
+Documentation = "https://gork.email/docs"
+Repository = "https://github.com/shyamcxy/gork-sdk-python"
+Issues = "https://github.com/shyamcxy/gork-sdk-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gork_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gork_sdk-0.1.0/src/gork/__init__.py

@@ -0,0 +1,30 @@
+"""gork.email Python SDK — programmable email infrastructure for AI agents."""
+
+from .client import GorkClient
+from .errors import GorkError
+from .types import (
+    Inbox,
+    Message,
+    Thread,
+    Webhook,
+    ApiKey,
+    Domain,
+    Suppression,
+)
+
+Gork = GorkClient
+
+__all__ = [
+    "Gork",
+    "GorkClient",
+    "GorkError",
+    "Inbox",
+    "Message",
+    "Thread",
+    "Webhook",
+    "ApiKey",
+    "Domain",
+    "Suppression",
+]
+
+__version__ = "0.1.0"

gork_sdk-0.1.0/src/gork/client.py

@@ -0,0 +1,468 @@
+"""GorkClient — zero-dependency (stdlib only) REST client for api.gork.email."""
+
+import hashlib
+import hmac
+import time
+import json
+import os
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from .errors import GorkError
+
+DEFAULT_BASE_URL = "https://api.gork.email"
+
+
+def verify_signature(
+    payload: str, signature_header: str, secret: str, tolerance_seconds: int = 300
+) -> bool:
+    """Verify an X-Gork-Signature webhook header (HMAC-SHA256).
+
+    Rejects signatures older than ``tolerance_seconds`` (default 300s,
+    matching the TypeScript verifiers) to prevent replay attacks.
+    """
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
+        timestamp, signature = parts.get("t", ""), parts.get("v1", "")
+        if not timestamp or not signature:
+            return False
+        # Freshness check — a captured payload+signature must not verify
+        # forever (previously there was no tolerance window at all).
+        if abs(time.time() - int(timestamp)) > tolerance_seconds:
+            return False
+        expected = hmac.new(
+            secret.encode(), f"{timestamp}.{payload}".encode(), hashlib.sha256
+        ).hexdigest()
+        return hmac.compare_digest(signature, expected)
+    except Exception:
+        return False
+
+
+def _client_version() -> str:
+    """Version reported in the User-Agent header.
+
+    Read from the installed distribution metadata so it always matches the
+    released version; falls back to the source version when running from a
+    checkout that was never installed.
+    """
+    try:
+        from importlib.metadata import version as _v
+
+        return _v("gork-sdk")
+    except Exception:
+        return "0.1.0"
+
+
+class GorkClient:
+    def __init__(self, api_key: str = "", base_url: str = DEFAULT_BASE_URL):
+        self.api_key = api_key or os.environ.get("GORK_KEY") or os.environ.get("GORK_API_KEY") or ""
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if not self.api_key:
+            import warnings
+
+            warnings.warn(
+                "[gork] initialized without an api_key. Set GORK_KEY or pass api_key explicitly."
+            )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("User-Agent", f"gork-sdk-python/{_client_version()}")
+        for k, v in (headers or {}).items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=30) as res:
+                payload = json.loads(res.read().decode() or "{}")
+        except urllib.error.HTTPError as e:
+            try:
+                payload = json.loads(e.read().decode() or "{}")
+            except Exception:
+                payload = {}
+            err = (payload.get("error") or {}) if isinstance(payload, dict) else {}
+            raise GorkError(
+                err.get("message") or f"API request failed with status {e.code}",
+                err.get("code") or "api_error",
+                e.code,
+                err.get("details"),
+            )
+        data_key = payload.get("data", payload) if isinstance(payload, dict) else payload
+        return data_key
+
+    def _request_bytes(self, path: str, inline: bool = False) -> bytes:
+        """Fetch a binary endpoint (attachment bytes) rather than JSON."""
+        url = self.base_url + path
+        if inline:
+            url += "?inline=1"
+        req = urllib.request.Request(url, method="GET")
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("User-Agent", f"gork-sdk-python/{_client_version()}")
+        try:
+            with urllib.request.urlopen(req, timeout=60) as res:
+                return res.read()
+        except urllib.error.HTTPError as e:
+            try:
+                payload = json.loads(e.read().decode() or "{}")
+            except Exception:
+                payload = {}
+            err = (payload.get("error") or {}) if isinstance(payload, dict) else {}
+            raise GorkError(
+                err.get("message") or f"API request failed with status {e.code}",
+                err.get("code") or "api_error",
+                e.code,
+                err.get("details"),
+            )
+
+    # ---- Inboxes ----
+    def create_inbox(self, username: str = "", name: str = "") -> Dict[str, Any]:
+        return self._request("POST", "/v1/inboxes", {"username": username, "name": name})
+
+    def list_inboxes(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/inboxes")
+
+    def get_inbox(self, inbox_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/inboxes/{urllib.parse.quote(inbox_id)}")
+
+    def delete_inbox(self, inbox_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/inboxes/{urllib.parse.quote(inbox_id)}")
+
+    # ---- Messages ----
+    def send_message(
+        self,
+        inbox_id: str,
+        to: List[str],
+        subject: str = "(no subject)",
+        text: str = "",
+        html: str = "",
+        in_reply_to: str = "",
+        idempotency_key: str = "",
+        attachments: Optional[List[Dict[str, Any]]] = None,
+        send_at: str = "",
+        track_opens: bool = False,
+    ) -> Dict[str, Any]:
+        """Send (or schedule) an outbound email.
+
+        attachments: [{"filename": "invoice.pdf", "contentType": "application/pdf",
+                       "content": "<base64>"}] — max 10 files, 10MB each, 15MB total.
+        send_at: ISO 8601 timestamp to schedule instead of sending now
+                 (1 minute to 30 days ahead). No quota is used until it dispatches.
+        track_opens: opt in to open tracking (adds a signed pixel, fires
+                     email.opened on the first open).
+        """
+        body: Dict[str, Any] = {"inboxId": inbox_id, "to": to, "subject": subject}
+        if text:
+            body["text"] = text
+        if html:
+            body["html"] = html
+        if in_reply_to:
+            body["inReplyTo"] = in_reply_to
+        if attachments:
+            body["attachments"] = attachments
+        if send_at:
+            body["sendAt"] = send_at
+        if track_opens:
+            body["trackOpens"] = True
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/v1/messages/send", body, headers=headers)
+
+    def cancel_scheduled(self, message_id: str) -> Dict[str, Any]:
+        """Cancel a scheduled send before it dispatches."""
+        return self._request(
+            "DELETE", f"/v1/messages/{urllib.parse.quote(message_id)}/schedule"
+        )
+
+    def list_messages(
+        self,
+        inbox_id: str = "",
+        thread_id: str = "",
+        limit: int = 50,
+        q: str = "",
+        direction: str = "",
+        from_address: str = "",
+        since: str = "",
+        until: str = "",
+    ) -> List[Dict[str, Any]]:
+        return self._request(
+            "GET", "/v1/messages",
+            query={
+                "inboxId": inbox_id or None,
+                "threadId": thread_id or None,
+                "limit": limit,
+                "q": q or None,
+                "direction": direction or None,
+                "from": from_address or None,
+                "since": since or None,
+                "until": until or None,
+            },
+        )
+
+    def search_messages(self, query: str, **filters: Any) -> List[Dict[str, Any]]:
+        """Search subject, body, sender and recipients (newest first)."""
+        return self.list_messages(q=query, **filters)
+
+    def download_attachment(self, attachment_id: str, inline: bool = False) -> bytes:
+        """Download an attachment's bytes. Ids come from a message's `attachments`."""
+        return self._request_bytes(
+            f"/v1/attachments/{urllib.parse.quote(attachment_id)}", inline=inline
+        )
+
+    # ---- Drafts (compose without sending; no quota used) ----
+    def create_draft(
+        self,
+        inbox_id: str,
+        to: Optional[List[str]] = None,
+        subject: str = "",
+        text: str = "",
+        html: str = "",
+        in_reply_to: str = "",
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"inboxId": inbox_id}
+        if to:
+            body["to"] = to
+        if subject:
+            body["subject"] = subject
+        if text:
+            body["text"] = text
+        if html:
+            body["html"] = html
+        if in_reply_to:
+            body["inReplyTo"] = in_reply_to
+        return self._request("POST", "/v1/drafts", body)
+
+    def list_drafts(
+        self, inbox_id: str = "", status: str = "draft", limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        return self._request(
+            "GET", "/v1/drafts",
+            query={
+                "inboxId": inbox_id or None,
+                "status": status or None,
+                "limit": limit,
+            },
+        )
+
+    def get_draft(self, draft_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/drafts/{urllib.parse.quote(draft_id)}")
+
+    def update_draft(self, draft_id: str, **fields: Any) -> Dict[str, Any]:
+        """Update draft fields, e.g. update_draft(id, subject="Hi", to=["a@b.com"])."""
+        return self._request(
+            "PATCH", f"/v1/drafts/{urllib.parse.quote(draft_id)}", fields
+        )
+
+    def discard_draft(self, draft_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/drafts/{urllib.parse.quote(draft_id)}")
+
+    def send_draft(self, draft_id: str) -> Dict[str, Any]:
+        """Send a draft through the full pipeline. Idempotent per draft."""
+        return self._request(
+            "POST", f"/v1/drafts/{urllib.parse.quote(draft_id)}/send"
+        )
+
+    def get_message(self, message_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/messages/{urllib.parse.quote(message_id)}")
+
+    # ---- Threads ----
+    def list_threads(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/threads")
+
+    def get_thread(self, thread_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/threads/{urllib.parse.quote(thread_id)}")
+
+    # ---- Webhooks ----
+    def create_webhook(self, url: str, events: Optional[List[str]] = None) -> Dict[str, Any]:
+        return self._request(
+            "POST", "/v1/webhooks",
+            {"url": url, "subscribedEvents": events or ["email.received", "email.sent", "email.bounced"]},
+        )
+
+    def list_webhooks(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/webhooks")
+
+    def rotate_webhook_secret(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/webhooks/{urllib.parse.quote(webhook_id)}/rotate-secret")
+
+    def delete_webhook(self, webhook_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/webhooks/{urllib.parse.quote(webhook_id)}")
+
+    def list_deliveries(self, limit: int = 50) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/webhooks/deliveries", query={"limit": limit})
+
+    # ---- API keys ----
+    def create_api_key(self, name: str, scopes: Optional[List[str]] = None) -> Dict[str, Any]:
+        return self._request("POST", "/v1/keys", {"name": name, "scopes": scopes or ["*"]})
+
+    def list_api_keys(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/keys")
+
+    def revoke_api_key(self, key_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/keys/{urllib.parse.quote(key_id)}")
+
+    # ---- Domains ----
+    def create_domain(self, domain: str) -> Dict[str, Any]:
+        return self._request("POST", "/v1/domains", {"domain": domain})
+
+    def list_domains(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/domains")
+
+    def verify_domain(self, domain_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/domains/{urllib.parse.quote(domain_id)}/verify")
+
+    def delete_domain(self, domain_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/domains/{urllib.parse.quote(domain_id)}")
+
+    # ---- Suppressions ----
+    def list_suppressions(self) -> List[Dict[str, Any]]:
+        return self._request("GET", "/v1/suppressions")
+
+    def suppress(self, email: str, reason: str = "manual") -> Dict[str, Any]:
+        return self._request("POST", "/v1/suppressions", {"email": email, "reason": reason})
+
+    def unsuppress(self, suppression_id: str) -> Dict[str, Any]:
+        return self._request("DELETE", f"/v1/suppressions/{urllib.parse.quote(suppression_id)}")
+
+    # ---- AI Agent Tools (OpenAI / Anthropic / LangChain / CrewAI compatible) ----
+    def get_tools(self) -> List[Dict[str, Any]]:
+        """Return standard function-calling tool schemas for OpenAI, Anthropic, or LangChain."""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_create_inbox",
+                    "description": "Provision a new programmable email inbox for an AI agent.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "username": {"type": "string", "description": "Lowercase username, e.g. sdr-alex"},
+                            "name": {"type": "string", "description": "Friendly agent display name"},
+                        },
+                        "required": ["username"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_list_inboxes",
+                    "description": "List all email inboxes available to the organization.",
+                    "parameters": {"type": "object", "properties": {}},
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_send_email",
+                    "description": "Send an outbound email from an agent inbox.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "inbox_id": {"type": "string", "description": "The ID of the inbox to send from"},
+                            "to": {"type": "array", "items": {"type": "string"}, "description": "Recipient email addresses"},
+                            "subject": {"type": "string", "description": "Email subject line"},
+                            "text": {"type": "string", "description": "Plain text email body"},
+                        },
+                        "required": ["inbox_id", "to", "subject", "text"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_read_emails",
+                    "description": "List or search messages, optionally filtered by inbox.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "inbox_id": {"type": "string", "description": "Filter by inbox ID"},
+                            "limit": {"type": "integer", "description": "Max messages to return (default 20)"},
+                        },
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_get_message",
+                    "description": "Retrieve full details and content of a specific email message.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "message_id": {"type": "string", "description": "The ID of the message (msg_...)"},
+                        },
+                        "required": ["message_id"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_create_draft",
+                    "description": "Create an email draft for review before sending.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "inbox_id": {"type": "string", "description": "Inbox ID"},
+                            "to": {"type": "array", "items": {"type": "string"}, "description": "Recipient addresses"},
+                            "subject": {"type": "string", "description": "Subject line"},
+                            "text": {"type": "string", "description": "Plain text body"},
+                        },
+                        "required": ["inbox_id", "to", "subject", "text"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "gork_send_draft",
+                    "description": "Send an existing email draft.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "draft_id": {"type": "string", "description": "Draft ID (drf_...)"},
+                        },
+                        "required": ["draft_id"],
+                    },
+                },
+            },
+        ]
+
+    def execute_tool(self, name: str, arguments: Dict[str, Any]) -> Any:
+        """Execute a tool called by an LLM function call."""
+        if name == "gork_create_inbox":
+            return self.create_inbox(arguments["username"], name=arguments.get("name"))
+        elif name == "gork_list_inboxes":
+            return self.list_inboxes()
+        elif name == "gork_send_email":
+            return self.send_message(
+                inbox_id=arguments["inbox_id"],
+                to=arguments["to"],
+                subject=arguments["subject"],
+                text=arguments["text"],
+            )
+        elif name == "gork_read_emails":
+            return self.list_messages(inbox_id=arguments.get("inbox_id"), limit=arguments.get("limit", 20))
+        elif name == "gork_get_message":
+            return self.get_message(arguments["message_id"])
+        elif name == "gork_create_draft":
+            return self.create_draft(
+                inbox_id=arguments["inbox_id"],
+                to=arguments["to"],
+                subject=arguments["subject"],
+                text=arguments["text"],
+            )
+        elif name == "gork_send_draft":
+            return self.send_draft(arguments["draft_id"])
+        else:
+            raise ValueError(f"Unknown Gork tool: {name}")

gork_sdk-0.1.0/src/gork/errors.py

@@ -0,0 +1,9 @@
+"""Error type carrying the API's stable error code."""
+
+
+class GorkError(Exception):
+    def __init__(self, message: str, code: str = "api_error", status: int = 0, details=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details

gork_sdk-0.1.0/src/gork/types.py

@@ -0,0 +1,59 @@
+"""TypedDict shapes mirroring the gork.email API envelopes."""
+
+from typing import List, Optional, TypedDict
+
+
+class Inbox(TypedDict, total=False):
+    id: str
+    address: str
+    name: Optional[str]
+    isActive: bool
+    createdAt: str
+
+
+class Message(TypedDict, total=False):
+    id: str
+    threadId: str
+    inboxId: str
+    direction: str
+    fromAddress: str
+    subject: str
+    textBody: Optional[str]
+    status: str
+    createdAt: str
+
+
+class Thread(TypedDict, total=False):
+    id: str
+    subject: str
+    messageCount: int
+    lastMessageAt: str
+
+
+class Webhook(TypedDict, total=False):
+    id: str
+    url: str
+    subscribedEvents: List[str]
+    isActive: bool
+    secret: Optional[str]
+
+
+class ApiKey(TypedDict, total=False):
+    id: str
+    name: str
+    keyPrefix: str
+    apiKey: Optional[str]
+    scopes: List[str]
+    createdAt: str
+
+
+class Domain(TypedDict, total=False):
+    id: str
+    domainName: str
+    status: str
+
+
+class Suppression(TypedDict, total=False):
+    id: str
+    email: str
+    reason: str

gork_sdk-0.1.0/src/gork_sdk.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: gork-sdk
+Version: 0.1.0
+Summary: Official Python SDK for gork.email programmable email infrastructure for AI agents
+Author: gork.email
+License: MIT
+Project-URL: Homepage, https://gork.email
+Project-URL: Documentation, https://gork.email/docs
+Project-URL: Repository, https://github.com/shyamcxy/gork-sdk-python
+Project-URL: Issues, https://github.com/shyamcxy/gork-sdk-python/issues
+Keywords: email,agent,ai,mcp,inbox,mail
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gork-sdk — Python SDK for gork.email
+
+> **Pre-alpha (0.1.0).** gork.email is in active development and the API may change between 0.x releases without a major bump. Pin an exact version in production.
+
+Programmable email infrastructure for AI agents. Provision inboxes, send and
+receive mail, search a mailbox, compose drafts, schedule sends, read
+attachments, and manage threads, webhooks, domains, keys, and suppressions.
+
+This SDK tracks the REST API at `https://api.gork.email/v1` and the TypeScript
+SDK (`@gork/sdk`); the method names and parameters match.
+
+## Install
+
+```bash
+pip install gork-sdk
+```
+
+## Quickstart
+
+```python
+from gork import GorkClient
+
+gork = GorkClient()  # reads GORK_KEY / GORK_API_KEY
+
+inbox = gork.create_inbox(username="sdr-alex", name="SDR Alex")
+print(inbox["address"])  # sdr-alex@try.gork.email
+
+gork.send_message(
+    inbox_id=inbox["id"],
+    to=["prospect@acme.com"],
+    subject="Quick intro",
+    text="Hi — wanted to share what we're building.",
+    idempotency_key="outreach-001",  # safe retries
+)
+```
+
+## Webhook verification
+
+```python
+from gork import verify_signature
+
+ok = verify_signature(raw_body, request.headers["X-Gork-Signature"], webhook_secret)
+```
+
+## Links
+
+- Docs: https://gork.email/docs
+- API reference: https://api.gork.email/openapi.json
+- Changelog: https://gork.email/changelog

gork_sdk-0.1.0/src/gork_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/gork/__init__.py
+src/gork/client.py
+src/gork/errors.py
+src/gork/types.py
+src/gork_sdk.egg-info/PKG-INFO
+src/gork_sdk.egg-info/SOURCES.txt
+src/gork_sdk.egg-info/dependency_links.txt
+src/gork_sdk.egg-info/top_level.txt
+tests/test_client_requests.py

gork_sdk-0.1.0/src/gork_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gork_sdk-0.1.0/src/gork_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+gork

gork_sdk-0.1.0/tests/test_client_requests.py

@@ -0,0 +1,110 @@
+"""Smoke test: the new methods build the right requests (no network)."""
+import json, sys, urllib.request
+sys.path.insert(0, "src")
+from gork import GorkClient
+
+calls = []
+
+class FakeResponse:
+    def __init__(self, payload): self._payload = payload
+    def read(self): return json.dumps(self._payload).encode()
+    def __enter__(self): return self
+    def __exit__(self, *a): return False
+
+def fake_urlopen(req, timeout=None):
+    calls.append({
+        "url": req.full_url,
+        "method": req.get_method(),
+        "body": json.loads(req.data.decode()) if req.data else None,
+        "headers": dict(req.headers),
+    })
+    if "attachments" in req.full_url and "/v1/attachments/" in req.full_url:
+        return FakeResponseBytes(b"FILE-BYTES")
+    return FakeResponse({"data": {"id": "msg_1", "status": "delivered"}})
+
+class FakeResponseBytes:
+    def __init__(self, b): self._b = b
+    def read(self): return self._b
+    def __enter__(self): return self
+    def __exit__(self, *a): return False
+
+urllib.request.urlopen = fake_urlopen
+client = GorkClient(api_key="gork_live_test")
+
+# attachments + tracking on send
+client.send_message("inb_1", ["a@b.com"], subject="Invoice", text="hi",
+                    attachments=[{"filename": "i.pdf", "contentType": "application/pdf", "content": "UERG"}],
+                    track_opens=True)
+body = calls[-1]["body"]
+assert body["attachments"][0]["filename"] == "i.pdf", body
+assert body["trackOpens"] is True
+
+# scheduling
+client.send_message("inb_1", ["a@b.com"], subject="Later", send_at="2026-09-12T10:00:00.000Z")
+assert calls[-1]["body"]["sendAt"] == "2026-09-12T10:00:00.000Z"
+
+# search filters reach the query string
+client.search_messages("invoice", direction="inbound")
+assert "q=invoice" in calls[-1]["url"], calls[-1]["url"]
+assert "direction=inbound" in calls[-1]["url"]
+
+# draft lifecycle
+client.create_draft("inb_1", to=["a@b.com"], subject="Draft")
+assert calls[-1]["method"] == "POST" and calls[-1]["url"].endswith("/v1/drafts")
+client.update_draft("drf_1", subject="Edited")
+assert calls[-1]["method"] == "PATCH"
+client.send_draft("drf_1")
+assert calls[-1]["url"].endswith("/v1/drafts/drf_1/send")
+client.discard_draft("drf_1")
+assert calls[-1]["method"] == "DELETE"
+
+# attachment bytes
+data = client.download_attachment("att_1")
+assert data == b"FILE-BYTES", data
+
+# cancel a schedule
+client.cancel_scheduled("msg_1")
+assert calls[-1]["method"] == "DELETE" and calls[-1]["url"].endswith("/schedule")
+
+# AI agent function tools
+tools = client.get_tools()
+assert len(tools) >= 6
+assert any(t["function"]["name"] == "gork_send_email" for t in tools)
+client.execute_tool("gork_send_email", {
+    "inbox_id": "inb_1",
+    "to": ["ai@example.com"],
+    "subject": "Agent Hello",
+    "text": "Sent via tool",
+})
+assert calls[-1]["body"]["to"] == ["ai@example.com"]
+
+print("python SDK smoke test passed:", len(calls), "calls checked")
+
+
+# ── Version drift guard ────────────────────────────────────────────────────
+# The User-Agent header used to hardcode a version string; it now reads the
+# installed distribution metadata, and these keep it honest and pre-alpha.
+def test_version_matches_pyproject():
+    import re, pathlib
+    root = pathlib.Path(__file__).resolve().parent.parent
+    declared = re.search(r'^version = "([^"]+)"', (root / "pyproject.toml").read_text(), re.M).group(1)
+    assert declared == "0.1.0", f"expected the 0.x pre-alpha line, got {declared}"
+
+
+def test_user_agent_uses_the_helper():
+    import pathlib
+    src = (pathlib.Path(__file__).resolve().parent.parent / "src" / "gork" / "client.py").read_text()
+    assert "gork-sdk-python/{_client_version()}" in src
+    assert not __import__("re").search(r'gork-sdk-python/\d', src)
+
+
+def test_reported_version_is_pre_alpha():
+    import sys, pathlib
+    sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "src"))
+    from gork.client import _client_version
+    assert _client_version().startswith("0.")
+
+test_version_matches_pyproject()
+test_user_agent_uses_the_helper()
+test_reported_version_is_pre_alpha()
+print("all version drift guards passed")