lumbox 0.3.0__tar.gz

lumbox-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: lumbox
+Version: 0.3.0
+Summary: Lumbox SDK — Email for AI agents. Create inboxes, receive OTPs, send replies.
+License-Expression: MIT
+Project-URL: Homepage, https://lumbox.co
+Project-URL: Repository, https://github.com/kumard3/agentinbox
+Project-URL: Documentation, https://docs.lumbox.co
+Keywords: email,ai,agents,otp,mcp,lumbox,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80.0; extra == "crewai"
+
+# lumbox
+
+Email for AI agents. Create inboxes, receive OTPs, extract verification codes — all via API.
+
+## Install
+
+```bash
+pip install lumbox
+```
+
+## Quick Start
+
+```python
+from lumbox import Lumbox
+
+client = Lumbox(api_key="ak_...")
+
+# Create an inbox
+inbox = client.create_inbox(name="github-bot")
+# → github-bot@lumbox.co
+
+# Sign up on any service with inbox.address...
+
+# Wait for the OTP (blocks until it arrives)
+otp = inbox.wait_for_otp(timeout=60)
+print(otp["code"])  # "847291"
+```
+
+## Auth header
+
+The SDK sends `Authorization: Bearer ak_...` by default. The legacy
+`X-API-Key` header still works server-side. Raw HTTP example:
+
+```bash
+curl https://api.lumbox.co/v1/inboxes \
+  -H "Authorization: Bearer ak_your_key_here"
+```
+
+## Inbox-scoped API keys
+
+Mint a key that can only ever touch one inbox:
+
+```python
+created = client.inboxes.api_keys.create(inbox.id, name="ci-bot")
+print(created["api_key"])  # shown once
+
+client.inboxes.api_keys.list(inbox.id)
+client.inboxes.api_keys.delete(inbox.id, created["id"])
+```
+
+## Features
+
+- **OTP extraction** — verification codes parsed automatically
+- **Long-poll** — `wait_for_email()` and `wait_for_otp()` block until arrival
+- **Send/reply/forward** — full outbound email support
+- **Custom domains** — DKIM, SPF, DMARC verification
+- **LangChain & CrewAI** — pre-built tool wrappers
+
+## Framework Integration
+
+### LangChain
+
+```bash
+pip install lumbox[langchain]
+```
+
+```python
+from lumbox import create_langchain_tools
+
+tools = create_langchain_tools(api_key="ak_...")
+# Use tools directly with LangChain agents
+```
+
+### Any Framework
+
+```python
+from lumbox import lumbox_tools
+
+tools = lumbox_tools(api_key="ak_...")
+# Dict of plain functions with proper type hints
+```
+
+## API
+
+### `Lumbox(api_key, base_url?)`
+
+Create a client. `base_url` defaults to `https://api.lumbox.co`.
+
+### `client.create_inbox(name?, domain?)`
+
+Returns an `Inbox` object with `.address`, `.id`, and convenience methods.
+
+### `inbox.wait_for_otp(timeout?, sender?)`
+
+Blocks until an email with an OTP arrives.
+
+### `inbox.wait_for_email(timeout?, sender?, subject?)`
+
+Blocks until any email arrives.
+
+### `inbox.list_emails()`
+
+List all emails in the inbox.
+
+Full API docs: [docs.lumbox.co](https://docs.lumbox.co)
+
+## License
+
+MIT

lumbox-0.3.0/README.md

@@ -0,0 +1,109 @@
+# lumbox
+
+Email for AI agents. Create inboxes, receive OTPs, extract verification codes — all via API.
+
+## Install
+
+```bash
+pip install lumbox
+```
+
+## Quick Start
+
+```python
+from lumbox import Lumbox
+
+client = Lumbox(api_key="ak_...")
+
+# Create an inbox
+inbox = client.create_inbox(name="github-bot")
+# → github-bot@lumbox.co
+
+# Sign up on any service with inbox.address...
+
+# Wait for the OTP (blocks until it arrives)
+otp = inbox.wait_for_otp(timeout=60)
+print(otp["code"])  # "847291"
+```
+
+## Auth header
+
+The SDK sends `Authorization: Bearer ak_...` by default. The legacy
+`X-API-Key` header still works server-side. Raw HTTP example:
+
+```bash
+curl https://api.lumbox.co/v1/inboxes \
+  -H "Authorization: Bearer ak_your_key_here"
+```
+
+## Inbox-scoped API keys
+
+Mint a key that can only ever touch one inbox:
+
+```python
+created = client.inboxes.api_keys.create(inbox.id, name="ci-bot")
+print(created["api_key"])  # shown once
+
+client.inboxes.api_keys.list(inbox.id)
+client.inboxes.api_keys.delete(inbox.id, created["id"])
+```
+
+## Features
+
+- **OTP extraction** — verification codes parsed automatically
+- **Long-poll** — `wait_for_email()` and `wait_for_otp()` block until arrival
+- **Send/reply/forward** — full outbound email support
+- **Custom domains** — DKIM, SPF, DMARC verification
+- **LangChain & CrewAI** — pre-built tool wrappers
+
+## Framework Integration
+
+### LangChain
+
+```bash
+pip install lumbox[langchain]
+```
+
+```python
+from lumbox import create_langchain_tools
+
+tools = create_langchain_tools(api_key="ak_...")
+# Use tools directly with LangChain agents
+```
+
+### Any Framework
+
+```python
+from lumbox import lumbox_tools
+
+tools = lumbox_tools(api_key="ak_...")
+# Dict of plain functions with proper type hints
+```
+
+## API
+
+### `Lumbox(api_key, base_url?)`
+
+Create a client. `base_url` defaults to `https://api.lumbox.co`.
+
+### `client.create_inbox(name?, domain?)`
+
+Returns an `Inbox` object with `.address`, `.id`, and convenience methods.
+
+### `inbox.wait_for_otp(timeout?, sender?)`
+
+Blocks until an email with an OTP arrives.
+
+### `inbox.wait_for_email(timeout?, sender?, subject?)`
+
+Blocks until any email arrives.
+
+### `inbox.list_emails()`
+
+List all emails in the inbox.
+
+Full API docs: [docs.lumbox.co](https://docs.lumbox.co)
+
+## License
+
+MIT

lumbox-0.3.0/lumbox/__init__.py

@@ -0,0 +1,4 @@
+from lumbox.client import Lumbox, Inbox
+from lumbox.tools import lumbox_tools, create_langchain_tools
+
+__all__ = ["Lumbox", "Inbox", "lumbox_tools", "create_langchain_tools"]

lumbox-0.3.0/lumbox/client.py

@@ -0,0 +1,389 @@
+"""
+Lumbox Python SDK — Email for AI agents.
+
+Usage:
+    from lumbox import Lumbox
+
+    client = Lumbox(api_key="ak_...")
+    inbox = client.create_inbox(name="my-bot")
+    otp = inbox.wait_for_otp(sender="github.com", timeout=60)
+    print(otp["code"])  # "847291"
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Optional
+import httpx
+
+
+class LumboxError(Exception):
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self.body = body
+        super().__init__(f"API error {status}: {body}")
+
+
+@dataclass
+class Inbox:
+    """Handle to a single agent inbox. Use methods to read emails, wait for OTPs, etc."""
+
+    id: str
+    address: str
+    name: Optional[str]
+    status: str
+    created_at: str
+    _client: "Lumbox" = field(repr=False)
+
+    def list_emails(
+        self,
+        *,
+        sender: Optional[str] = None,
+        category: Optional[str] = None,
+        since: Optional[str] = None,
+        unread: bool = False,
+        limit: int = 20,
+    ) -> dict:
+        """List emails in this inbox."""
+        params: dict[str, Any] = {"limit": limit}
+        if sender:
+            params["from"] = sender
+        if category:
+            params["category"] = category
+        if since:
+            params["since"] = since
+        if unread:
+            params["unread"] = "true"
+        return self._client._get(f"/v1/inboxes/{self.id}/emails", params=params)
+
+    def get_email(self, email_id: str) -> dict:
+        """Get full email content including parsed data."""
+        return self._client._get(f"/v1/inboxes/{self.id}/emails/{email_id}")
+
+    def wait_for_email(
+        self,
+        *,
+        sender: Optional[str] = None,
+        subject: Optional[str] = None,
+        category: Optional[str] = None,
+        has_otp: bool = False,
+        timeout: int = 30,
+    ) -> dict:
+        """
+        Block until a matching email arrives. Returns the full parsed email.
+
+        This is the primary method for AI agents. After signing up on a platform:
+            email = inbox.wait_for_email(sender="github.com", timeout=60)
+            otp = email["parsed"]["otp_codes"][0]
+        """
+        params: dict[str, Any] = {"timeout": timeout}
+        if sender:
+            params["from"] = sender
+        if subject:
+            params["subject"] = subject
+        if category:
+            params["category"] = category
+        if has_otp:
+            params["has_otp"] = "true"
+        return self._client._get(f"/v1/inboxes/{self.id}/wait", params=params)
+
+    def wait_for_otp(
+        self,
+        *,
+        sender: Optional[str] = None,
+        timeout: int = 30,
+    ) -> dict:
+        """
+        Wait for an OTP/verification code. Returns just the code.
+
+        The simplest way for an agent to get a verification code:
+            result = inbox.wait_for_otp(sender="github.com", timeout=60)
+            code = result["code"]  # "847291"
+        """
+        params: dict[str, Any] = {"timeout": timeout}
+        if sender:
+            params["from"] = sender
+        return self._client._get(f"/v1/inboxes/{self.id}/otp", params=params)
+
+    def delete(self) -> dict:
+        """Delete this inbox and all its emails."""
+        return self._client._delete(f"/v1/inboxes/{self.id}")
+
+
+class Lumbox:
+    """
+    Lumbox client — create email inboxes for AI agents.
+
+    Args:
+        api_key: Your Lumbox API key (starts with 'ak_')
+        base_url: API base URL (default: https://api.lumbox.co)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.lumbox.co",
+    ):
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {api_key}",
+            },
+            timeout=httpx.Timeout(130),  # long timeout for /wait endpoints
+        )
+        self.inboxes = _InboxesNamespace(self)
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        resp = self._http.get(path, params=params)
+        data = resp.json()
+        if not resp.is_success:
+            raise LumboxError(resp.status_code, data)
+        return data
+
+    def _post(
+        self, path: str, json: Optional[dict] = None, idempotency_key: Optional[str] = None
+    ) -> dict:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        resp = self._http.post(path, json=json or {}, headers=headers)
+        data = resp.json()
+        if not resp.is_success:
+            raise LumboxError(resp.status_code, data)
+        return data
+
+    def _delete(self, path: str) -> dict:
+        resp = self._http.delete(path)
+        data = resp.json()
+        if not resp.is_success:
+            raise LumboxError(resp.status_code, data)
+        return data
+
+    def _to_inbox(self, data: dict) -> Inbox:
+        return Inbox(
+            id=data["id"],
+            address=data["address"],
+            name=data.get("name"),
+            status=data["status"],
+            created_at=data["created_at"],
+            _client=self,
+        )
+
+    # --- Inboxes ---
+
+    def create_inbox(
+        self,
+        *,
+        name: Optional[str] = None,
+        domain: Optional[str] = None,
+        local_part: Optional[str] = None,
+    ) -> Inbox:
+        """Create a new email inbox for an AI agent."""
+        body: dict[str, Any] = {}
+        if name:
+            body["name"] = name
+        if domain:
+            body["domain"] = domain
+        if local_part:
+            body["local_part"] = local_part
+        data = self._post("/v1/inboxes", json=body)
+        return self._to_inbox(data)
+
+    def list_inboxes(self) -> list[Inbox]:
+        """List all inboxes."""
+        res = self._get("/v1/inboxes")
+        return [self._to_inbox(d) for d in res["data"]]
+
+    def get_inbox(self, inbox_id: str) -> Inbox:
+        """Get an inbox by ID."""
+        data = self._get(f"/v1/inboxes/{inbox_id}")
+        return self._to_inbox(data)
+
+    # --- Domains ---
+
+    def add_domain(self, domain: str) -> dict:
+        """Add a custom domain. Returns DNS records to configure."""
+        return self._post("/v1/domains", json={"domain": domain})
+
+    def verify_domain(self, domain_id: str) -> dict:
+        """Verify DNS records and activate a domain."""
+        return self._post(f"/v1/domains/{domain_id}/verify")
+
+    def list_domains(self) -> dict:
+        """List all custom domains."""
+        return self._get("/v1/domains")
+
+    # --- Search ---
+
+    def search_emails(
+        self,
+        *,
+        query: Optional[str] = None,
+        sender: Optional[str] = None,
+        category: Optional[str] = None,
+        inbox_id: Optional[str] = None,
+    ) -> dict:
+        """Search emails across all inboxes."""
+        params: dict[str, Any] = {}
+        if query:
+            params["q"] = query
+        if sender:
+            params["from"] = sender
+        if category:
+            params["category"] = category
+        if inbox_id:
+            params["inbox_id"] = inbox_id
+        return self._get("/v1/emails", params=params)
+
+    def _patch(self, path: str, json: Optional[dict] = None) -> dict:
+        resp = self._http.patch(path, json=json or {})
+        data = resp.json()
+        if not resp.is_success:
+            raise LumboxError(resp.status_code, data)
+        return data
+
+    # --- SMTP Configuration (BYOS) ---
+
+    def configure_smtp(
+        self,
+        *,
+        provider: str,
+        name: Optional[str] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        api_key: Optional[str] = None,
+        region: Optional[str] = None,
+        from_email: Optional[str] = None,
+        is_default: bool = False,
+    ) -> dict:
+        """Configure a custom SMTP provider (BYOS)."""
+        body: dict[str, Any] = {"provider": provider, "is_default": is_default}
+        if name:
+            body["name"] = name
+        if host:
+            body["host"] = host
+        if port:
+            body["port"] = port
+        if username:
+            body["username"] = username
+        if password:
+            body["password"] = password
+        if api_key:
+            body["api_key"] = api_key
+        if region:
+            body["region"] = region
+        if from_email:
+            body["from_email"] = from_email
+        return self._post("/v1/smtp-configs", json=body)
+
+    def list_smtp_configs(self) -> dict:
+        """List all SMTP configurations."""
+        return self._get("/v1/smtp-configs")
+
+    def test_smtp_config(self, config_id: str, to: str) -> dict:
+        """Send a test email through an SMTP config."""
+        return self._post(f"/v1/smtp-configs/{config_id}/test", json={"to": to})
+
+    # --- Thread Routing ---
+
+    def assign_thread(
+        self,
+        thread_id: str,
+        agent_id: str,
+        *,
+        role: Optional[str] = None,
+    ) -> dict:
+        """Assign an agent to a thread."""
+        body: dict[str, Any] = {"agent_id": agent_id}
+        if role:
+            body["role"] = role
+        return self._post(f"/v1/threads/{thread_id}/assign", json=body)
+
+    def unassign_thread(self, thread_id: str, agent_id: str) -> dict:
+        """Unassign an agent from a thread."""
+        return self._post(f"/v1/threads/{thread_id}/unassign", json={"agent_id": agent_id})
+
+    def list_thread_agents(self, thread_id: str) -> dict:
+        """List agents assigned to a thread."""
+        return self._get(f"/v1/threads/{thread_id}/agents")
+
+    def create_routing_rule(
+        self,
+        *,
+        name: str,
+        conditions: dict,
+        target_agent_id: Optional[str] = None,
+        target_inbox_id: Optional[str] = None,
+        priority: int = 0,
+    ) -> dict:
+        """Create an auto-routing rule for thread assignment."""
+        body: dict[str, Any] = {
+            "name": name,
+            "conditions": conditions,
+            "priority": priority,
+        }
+        if target_agent_id:
+            body["target_agent_id"] = target_agent_id
+        if target_inbox_id:
+            body["target_inbox_id"] = target_inbox_id
+        return self._post("/v1/routing-rules", json=body)
+
+    def list_routing_rules(self) -> dict:
+        """List all routing rules."""
+        return self._get("/v1/routing-rules")
+
+    def delete_routing_rule(self, rule_id: str) -> dict:
+        """Delete a routing rule."""
+        return self._delete(f"/v1/routing-rules/{rule_id}")
+
+    # --- Webhooks ---
+
+    def create_webhook(self, url: str, *, events: Optional[list[str]] = None) -> dict:
+        """Register a webhook URL for real-time notifications."""
+        body: dict[str, Any] = {"url": url}
+        if events:
+            body["events"] = events
+        return self._post("/v1/webhooks", json=body)
+
+    def list_webhooks(self) -> dict:
+        """List all webhooks."""
+        return self._get("/v1/webhooks")
+
+    def test_webhook(self, webhook_id: str) -> dict:
+        """Send a test payload to a webhook."""
+        return self._post(f"/v1/webhooks/{webhook_id}/test")
+
+    def delete_webhook(self, webhook_id: str) -> dict:
+        """Delete a webhook."""
+        return self._delete(f"/v1/webhooks/{webhook_id}")
+
+
+class _InboxApiKeys:
+    """Manage API keys scoped to a single inbox."""
+
+    def __init__(self, client: "Lumbox"):
+        self._client = client
+
+    def create(self, inbox_id: str, *, name: str) -> dict:
+        """Mint a new key locked to this inbox. The plaintext key is returned only once."""
+        return self._client._post(
+            f"/v1/inboxes/{inbox_id}/api-keys",
+            json={"name": name},
+        )
+
+    def list(self, inbox_id: str) -> dict:
+        """List keys scoped to this inbox."""
+        return self._client._get(f"/v1/inboxes/{inbox_id}/api-keys")
+
+    def delete(self, inbox_id: str, key_id: str) -> dict:
+        """Revoke an inbox-scoped key."""
+        return self._client._delete(f"/v1/inboxes/{inbox_id}/api-keys/{key_id}")
+
+
+class _InboxesNamespace:
+    """Namespace accessor: ``client.inboxes.api_keys.create(...)``."""
+
+    def __init__(self, client: "Lumbox"):
+        self.api_keys = _InboxApiKeys(client)

lumbox-0.3.0/lumbox/tools.py

@@ -0,0 +1,255 @@
+"""
+Pre-built tool wrappers for popular AI agent frameworks.
+
+Works with: LangChain, CrewAI, OpenAI Agents SDK, Vercel AI SDK, LlamaIndex, AutoGen
+
+Usage (LangChain):
+    from lumbox import create_langchain_tools
+    tools = create_langchain_tools(api_key="ak_...")
+
+Usage (any framework — raw function tools):
+    from lumbox import lumbox_tools
+    tools = lumbox_tools(api_key="ak_...")
+"""
+
+from __future__ import annotations
+from typing import Optional
+from lumbox.client import Lumbox
+
+
+def lumbox_tools(
+    api_key: str,
+    base_url: str = "https://api.lumbox.co",
+) -> dict:
+    """
+    Returns a dict of plain functions that any framework can use as tools.
+    Each function has proper type hints and docstrings for schema generation.
+
+    Returns:
+        {
+            "create_inbox": <function>,
+            "wait_for_email": <function>,
+            "get_otp": <function>,
+            "list_emails": <function>,
+            "read_email": <function>,
+            "search_emails": <function>,
+            "add_domain": <function>,
+            "verify_domain": <function>,
+        }
+    """
+    client = Lumbox(api_key=api_key, base_url=base_url)
+
+    def create_inbox(name: str = "", domain: str = "") -> str:
+        """Create a new email inbox for an AI agent.
+
+        Args:
+            name: Human-readable name like 'github-signup-bot'. Used as the email local part.
+            domain: Custom domain if configured. Leave empty for default domain.
+
+        Returns:
+            JSON with inbox id, email address, and status.
+        """
+        inbox = client.create_inbox(
+            name=name or None,
+            domain=domain or None,
+        )
+        return f'{{"id": "{inbox.id}", "address": "{inbox.address}", "name": "{inbox.name}", "status": "{inbox.status}"}}'
+
+    def wait_for_email(
+        inbox_id: str,
+        sender: str = "",
+        subject: str = "",
+        category: str = "",
+        timeout: int = 30,
+    ) -> str:
+        """Wait for an email to arrive in an inbox. Blocks until received or timeout.
+
+        Use this after signing up on a platform to get the verification email.
+
+        Args:
+            inbox_id: The inbox ID to watch (e.g., inb_abc123).
+            sender: Filter by sender address or domain (e.g., 'github.com').
+            subject: Filter by subject keyword.
+            category: Filter by category: verification, security, notification, transactional, newsletter.
+            timeout: Max seconds to wait (default 30, max 120).
+
+        Returns:
+            JSON with full email data including parsed OTP codes and verification links.
+        """
+        import json
+
+        inbox = client.get_inbox(inbox_id)
+        result = inbox.wait_for_email(
+            sender=sender or None,
+            subject=subject or None,
+            category=category or None,
+            timeout=timeout,
+        )
+        return json.dumps(result, indent=2)
+
+    def get_otp(
+        inbox_id: str,
+        sender: str = "",
+        timeout: int = 30,
+    ) -> str:
+        """Get the latest OTP/verification code from an inbox. Blocks until one arrives.
+
+        The simplest way for an agent to get a verification code.
+
+        Args:
+            inbox_id: The inbox ID.
+            sender: Filter by sender (e.g., 'github.com').
+            timeout: Max seconds to wait (default 30, max 120).
+
+        Returns:
+            JSON with code, sender, subject, and expiry time.
+        """
+        import json
+
+        inbox = client.get_inbox(inbox_id)
+        result = inbox.wait_for_otp(sender=sender or None, timeout=timeout)
+        return json.dumps(result, indent=2)
+
+    def list_emails(
+        inbox_id: str,
+        sender: str = "",
+        category: str = "",
+        unread: bool = False,
+        limit: int = 10,
+    ) -> str:
+        """List emails in an inbox.
+
+        Args:
+            inbox_id: The inbox ID.
+            sender: Filter by sender.
+            category: Filter by category.
+            unread: Only show unread emails.
+            limit: Max emails to return (default 10).
+
+        Returns:
+            JSON array of emails with parsed data.
+        """
+        import json
+
+        inbox = client.get_inbox(inbox_id)
+        result = inbox.list_emails(
+            sender=sender or None,
+            category=category or None,
+            unread=unread,
+            limit=limit,
+        )
+        return json.dumps(result, indent=2)
+
+    def read_email(inbox_id: str, email_id: str) -> str:
+        """Read the full content of a specific email.
+
+        Args:
+            inbox_id: The inbox ID.
+            email_id: The email ID.
+
+        Returns:
+            JSON with full email content, parsed OTP codes, verification links, and AI summary.
+        """
+        import json
+
+        inbox = client.get_inbox(inbox_id)
+        result = inbox.get_email(email_id)
+        return json.dumps(result, indent=2)
+
+    def search_emails(
+        query: str = "",
+        sender: str = "",
+        category: str = "",
+        inbox_id: str = "",
+    ) -> str:
+        """Search emails across all inboxes.
+
+        Args:
+            query: Search query (searches subject, body, summary).
+            sender: Filter by sender.
+            category: Filter by category.
+            inbox_id: Limit to a specific inbox.
+
+        Returns:
+            JSON array of matching emails.
+        """
+        import json
+
+        result = client.search_emails(
+            query=query or None,
+            sender=sender or None,
+            category=category or None,
+            inbox_id=inbox_id or None,
+        )
+        return json.dumps(result, indent=2)
+
+    def add_domain(domain: str) -> str:
+        """Add a custom domain for agent email addresses.
+
+        Args:
+            domain: The domain to add (e.g., 'mycompany.com').
+
+        Returns:
+            JSON with domain ID and DNS records to configure.
+        """
+        import json
+
+        result = client.add_domain(domain)
+        return json.dumps(result, indent=2)
+
+    def verify_domain(domain_id: str) -> str:
+        """Verify DNS records and activate a custom domain.
+
+        Args:
+            domain_id: The domain ID to verify.
+
+        Returns:
+            JSON with verification status for each DNS record.
+        """
+        import json
+
+        result = client.verify_domain(domain_id)
+        return json.dumps(result, indent=2)
+
+    return {
+        "create_inbox": create_inbox,
+        "wait_for_email": wait_for_email,
+        "get_otp": get_otp,
+        "list_emails": list_emails,
+        "read_email": read_email,
+        "search_emails": search_emails,
+        "add_domain": add_domain,
+        "verify_domain": verify_domain,
+    }
+
+
+def create_langchain_tools(
+    api_key: str,
+    base_url: str = "https://api.lumbox.co",
+):
+    """
+    Create LangChain-compatible tools for Lumbox.
+
+    Usage:
+        from lumbox import create_langchain_tools
+        from langchain_openai import ChatOpenAI
+        from langchain.agents import create_tool_calling_agent, AgentExecutor
+
+        tools = create_langchain_tools(api_key="ak_...")
+        llm = ChatOpenAI(model="gpt-4o")
+        agent = create_tool_calling_agent(llm, tools, prompt)
+        executor = AgentExecutor(agent=agent, tools=tools)
+    """
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required. Install with: pip install lumbox[langchain]"
+        )
+
+    raw_tools = lumbox_tools(api_key=api_key, base_url=base_url)
+
+    return [
+        StructuredTool.from_function(func, name=name)
+        for name, func in raw_tools.items()
+    ]

lumbox-0.3.0/lumbox.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: lumbox
+Version: 0.3.0
+Summary: Lumbox SDK — Email for AI agents. Create inboxes, receive OTPs, send replies.
+License-Expression: MIT
+Project-URL: Homepage, https://lumbox.co
+Project-URL: Repository, https://github.com/kumard3/agentinbox
+Project-URL: Documentation, https://docs.lumbox.co
+Keywords: email,ai,agents,otp,mcp,lumbox,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80.0; extra == "crewai"
+
+# lumbox
+
+Email for AI agents. Create inboxes, receive OTPs, extract verification codes — all via API.
+
+## Install
+
+```bash
+pip install lumbox
+```
+
+## Quick Start
+
+```python
+from lumbox import Lumbox
+
+client = Lumbox(api_key="ak_...")
+
+# Create an inbox
+inbox = client.create_inbox(name="github-bot")
+# → github-bot@lumbox.co
+
+# Sign up on any service with inbox.address...
+
+# Wait for the OTP (blocks until it arrives)
+otp = inbox.wait_for_otp(timeout=60)
+print(otp["code"])  # "847291"
+```
+
+## Auth header
+
+The SDK sends `Authorization: Bearer ak_...` by default. The legacy
+`X-API-Key` header still works server-side. Raw HTTP example:
+
+```bash
+curl https://api.lumbox.co/v1/inboxes \
+  -H "Authorization: Bearer ak_your_key_here"
+```
+
+## Inbox-scoped API keys
+
+Mint a key that can only ever touch one inbox:
+
+```python
+created = client.inboxes.api_keys.create(inbox.id, name="ci-bot")
+print(created["api_key"])  # shown once
+
+client.inboxes.api_keys.list(inbox.id)
+client.inboxes.api_keys.delete(inbox.id, created["id"])
+```
+
+## Features
+
+- **OTP extraction** — verification codes parsed automatically
+- **Long-poll** — `wait_for_email()` and `wait_for_otp()` block until arrival
+- **Send/reply/forward** — full outbound email support
+- **Custom domains** — DKIM, SPF, DMARC verification
+- **LangChain & CrewAI** — pre-built tool wrappers
+
+## Framework Integration
+
+### LangChain
+
+```bash
+pip install lumbox[langchain]
+```
+
+```python
+from lumbox import create_langchain_tools
+
+tools = create_langchain_tools(api_key="ak_...")
+# Use tools directly with LangChain agents
+```
+
+### Any Framework
+
+```python
+from lumbox import lumbox_tools
+
+tools = lumbox_tools(api_key="ak_...")
+# Dict of plain functions with proper type hints
+```
+
+## API
+
+### `Lumbox(api_key, base_url?)`
+
+Create a client. `base_url` defaults to `https://api.lumbox.co`.
+
+### `client.create_inbox(name?, domain?)`
+
+Returns an `Inbox` object with `.address`, `.id`, and convenience methods.
+
+### `inbox.wait_for_otp(timeout?, sender?)`
+
+Blocks until an email with an OTP arrives.
+
+### `inbox.wait_for_email(timeout?, sender?, subject?)`
+
+Blocks until any email arrives.
+
+### `inbox.list_emails()`
+
+List all emails in the inbox.
+
+Full API docs: [docs.lumbox.co](https://docs.lumbox.co)
+
+## License
+
+MIT

lumbox-0.3.0/lumbox.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+lumbox/__init__.py
+lumbox/client.py
+lumbox/tools.py
+lumbox.egg-info/PKG-INFO
+lumbox.egg-info/SOURCES.txt
+lumbox.egg-info/dependency_links.txt
+lumbox.egg-info/requires.txt
+lumbox.egg-info/top_level.txt

lumbox-0.3.0/lumbox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lumbox-0.3.0/lumbox.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.27.0
+
+[crewai]
+crewai>=0.80.0
+
+[langchain]
+langchain-core>=0.3.0

lumbox-0.3.0/lumbox.egg-info/top_level.txt

@@ -0,0 +1 @@
+lumbox

lumbox-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lumbox"
+version = "0.3.0"
+description = "Lumbox SDK — Email for AI agents. Create inboxes, receive OTPs, send replies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27.0"]
+keywords = ["email", "ai", "agents", "otp", "mcp", "lumbox", "verification"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://lumbox.co"
+Repository = "https://github.com/kumard3/agentinbox"
+Documentation = "https://docs.lumbox.co"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3.0"]
+crewai = ["crewai>=0.80.0"]

lumbox-0.3.0/setup.cfg

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