mailwire-sdk 0.1.1__tar.gz

mailwire_sdk-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+.env
+.env.*
+!.env.example
+
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+scripts/.last_thread_id
+/inbound/
+
+/var/
+infra/.bootstrap_admin_key.txt
+
+.DS_Store
+
+.claude/
+

mailwire_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mailwire-sdk
+Version: 0.1.1
+Summary: Python SDK for mailwire-x1
+Requires-Python: <3.13,>=3.12
+Requires-Dist: httpx<0.28,>=0.27
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'

mailwire_sdk-0.1.1/README.md

@@ -0,0 +1,120 @@
+# mailwire-sdk
+
+Python SDK for [mailwire-x1](https://github.com/anthropics/mailwire-x1).
+
+## Install
+
+```bash
+pip install mailwire-sdk
+```
+
+To also install the MCP server entry point:
+
+```bash
+pip install 'mailwire-sdk[mcp]'
+```
+
+## Usage
+
+```python
+from mailwire_sdk import Client
+
+with Client(token="mw_live_...", base_url="https://api.example.com") as mw:
+    # Create an inbox on a verified tenant domain
+    inbox = mw.inboxes.create(
+        client_id="lena.taiwo",
+        display_name="Lena",
+        domain_id="dom_...",
+        shareable_local_part="lena",
+        private_address_count=2,
+    )
+
+    # Send a message
+    msg = mw.messages.send(
+        inbox_id=inbox["id"],
+        from_address="Lena <lena@someonehq.com>",
+        to=["recipient@example.com"],
+        subject="Catching up",
+        text="Hi — thinking of you.",
+        idempotency_key="20260503-lena-001",
+    )
+
+    # List recent messages
+    for m in mw.messages.list(inbox_id=inbox["id"], limit=20):
+        print(m["id"], m["subject"])
+```
+
+### Sub-clients
+
+| Attribute      | Resource                                              |
+|----------------|-------------------------------------------------------|
+| `mw.tenants`   | tenant CRUD (`admin` scope)                           |
+| `mw.api_keys`  | mint / list / get / revoke (`admin` scope)            |
+| `mw.domains`   | register, fetch DNS records, verify, delete           |
+| `mw.inboxes`   | create, list, get, update, archive, add_address       |
+| `mw.messages`  | send, list, get                                       |
+
+### Errors
+
+Every non-2xx response from mailwire becomes a typed exception:
+
+```python
+from mailwire_sdk import (
+    Client,
+    AuthError,
+    PermissionError,
+    NotFoundError,
+    ConflictError,
+    ValidationError,
+    ProviderError,
+    MailwireError,  # base — catch-all
+)
+
+try:
+    mw.messages.send(...)
+except ConflictError as exc:
+    # idempotency-key reused with a different body
+    print(exc.code, exc.details)
+except PermissionError as exc:
+    # token is missing the required scope
+    print("missing:", exc.details["required_scope"])
+except MailwireError as exc:
+    # any other API error — exc.type, exc.status_code, exc.request_id available
+    raise
+```
+
+## MCP server
+
+`mailwire-sdk[mcp]` ships a stdio MCP server. Wire it into Claude Desktop / your
+IDE:
+
+```json
+{
+  "mcpServers": {
+    "mailwire": {
+      "command": "mailwire-mcp",
+      "env": {
+        "MAILWIRE_BASE_URL": "https://api.example.com",
+        "MAILWIRE_TOKEN": "mw_live_..."
+      }
+    }
+  }
+}
+```
+
+Tools exposed:
+
+- `mailwire_list_inboxes`
+- `mailwire_get_inbox`
+- `mailwire_send_message`
+- `mailwire_list_messages`
+- `mailwire_get_message`
+
+See [`docs/mcp.md`](../../docs/mcp.md) for tool argument schemas and the
+end-to-end agent loop.
+
+## Versioning
+
+`mailwire-sdk 0.1.0` targets the mailwire-x1 v1 API. Breaking server changes go
+to a new `/v2/` surface and a major-version SDK bump. Additive changes (new
+optional fields, new endpoints) ship in patch / minor versions.

mailwire_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "mailwire-sdk"
+version = "0.1.1"
+description = "Python SDK for mailwire-x1"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "httpx>=0.27,<0.28",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0"]
+
+[project.scripts]
+mailwire-mcp = "mailwire_sdk.mcp_server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailwire_sdk"]

mailwire_sdk-0.1.1/src/mailwire_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""Python SDK for mailwire-x1.
+
+Public surface:
+    - `Client` — synchronous client (use as context manager).
+    - `MailwireError` and subclasses for catching API errors.
+"""
+
+from mailwire_sdk.client import Client
+from mailwire_sdk.errors import (
+    AuthError,
+    ConflictError,
+    MailwireError,
+    NotFoundError,
+    PermissionError,
+    ProviderError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthError",
+    "Client",
+    "ConflictError",
+    "MailwireError",
+    "NotFoundError",
+    "PermissionError",
+    "ProviderError",
+    "ServerError",
+    "ValidationError",
+    "__version__",
+]

mailwire_sdk-0.1.1/src/mailwire_sdk/_transport.py

@@ -0,0 +1,69 @@
+"""HTTP transport — wraps httpx.Client with auth + error envelope decoding."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from mailwire_sdk.errors import MailwireError, from_envelope
+
+
+class Transport:
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str,
+        timeout: float = 30.0,
+        user_agent: str = "mailwire-sdk-python/0.1.0",
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={
+                "Authorization": f"Bearer {token}",
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            response = self._client.request(
+                method, path, params=params, json=json, headers=headers
+            )
+        except httpx.RequestError as exc:
+            raise MailwireError(f"network error: {exc}") from exc
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise MailwireError(
+                f"non-JSON response (HTTP {response.status_code}): {response.text[:200]!r}"
+            ) from exc
+
+        if response.status_code >= 400:
+            raise from_envelope(payload, status_code=response.status_code)
+
+        return payload  # type: ignore[no-any-return]
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

mailwire_sdk-0.1.1/src/mailwire_sdk/client.py

@@ -0,0 +1,76 @@
+"""Top-level mailwire SDK client.
+
+The synchronous `Client` is the v0 surface — async support and generated typed
+models land in Sprint 5. Usage:
+
+    from mailwire_sdk import Client
+    with Client(token="mw_live_...", base_url="https://api.example.com") as mw:
+        inbox = mw.inboxes.create(
+            client_id="lena.taiwo",
+            display_name="Lena",
+            domain_id="dom_...",
+            shareable_local_part="lena",
+            private_address_count=2,
+        )
+        mw.messages.send(
+            inbox_id=inbox["id"],
+            from_address="Lena <lena@someonehq.com>",
+            to=["recipient@example.com"],
+            subject="Catching up",
+            text="...",
+        )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+from mailwire_sdk.resources import (
+    ApiKeysResource,
+    DomainsResource,
+    InboxesResource,
+    MessagesResource,
+    TenantsResource,
+    ThreadsResource,
+    WebhooksResource,
+)
+
+
+class Client:
+    """Synchronous mailwire client.
+
+    Use as a context manager (recommended) or call `.close()` when done. Each
+    `Client` owns a pooled `httpx.Client` under the hood.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        base_url: str = "http://localhost:8083",
+        timeout: float = 30.0,
+    ) -> None:
+        self._transport = Transport(token=token, base_url=base_url, timeout=timeout)
+        self.tenants = TenantsResource(self._transport)
+        self.api_keys = ApiKeysResource(self._transport)
+        self.domains = DomainsResource(self._transport)
+        self.inboxes = InboxesResource(self._transport)
+        self.messages = MessagesResource(self._transport)
+        self.threads = ThreadsResource(self._transport)
+        self.webhooks = WebhooksResource(self._transport)
+
+    def healthz(self) -> dict[str, Any]:
+        """Service health probe — no auth required server-side, but the SDK
+        still sends the bearer header. Returns `{"status": "ok", "version": ...}`.
+        """
+        return self._transport.request("GET", "/healthz")
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

mailwire_sdk-0.1.1/src/mailwire_sdk/errors.py

@@ -0,0 +1,90 @@
+"""SDK error hierarchy mirrors the API error envelope.
+
+Server response:
+
+    { "error": { "type": "validation_error", "code": "...", "message": "...",
+                 "request_id": "...", "details": {...} } }
+
+is parsed and raised as a typed subclass of `MailwireError`. Callers can either
+catch the broad `MailwireError` or be specific (`AuthError`, `NotFoundError`,
+`ConflictError`, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class MailwireError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        type: str | None = None,
+        code: str | None = None,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.type = type
+        self.code = code
+        self.status_code = status_code
+        self.details: dict[str, Any] = details or {}
+        self.request_id = request_id
+
+
+class AuthError(MailwireError):
+    """401 — missing or invalid bearer token."""
+
+
+class PermissionError(MailwireError):
+    """403 — token lacks required scope."""
+
+
+class NotFoundError(MailwireError):
+    """404 — resource missing or owned by another tenant."""
+
+
+class ConflictError(MailwireError):
+    """409 — uniqueness conflict or idempotency-key reuse with a different body."""
+
+
+class ValidationError(MailwireError):
+    """422 / 400 — request body failed validation."""
+
+
+class ProviderError(MailwireError):
+    """502/503-ish — upstream provider failed."""
+
+
+class ServerError(MailwireError):
+    """5xx — internal error."""
+
+
+_BY_TYPE: dict[str, type[MailwireError]] = {
+    "auth_error": AuthError,
+    "permission_error": PermissionError,
+    "not_found": NotFoundError,
+    "conflict": ConflictError,
+    "validation_error": ValidationError,
+    "request_error": ValidationError,
+    "provider_error": ProviderError,
+    "server_error": ServerError,
+}
+
+
+def from_envelope(envelope: dict[str, Any], *, status_code: int) -> MailwireError:
+    """Construct the right subclass from an `{"error": {...}}` payload."""
+    err = envelope.get("error", envelope)
+    cls = _BY_TYPE.get(err.get("type", ""), MailwireError)
+    return cls(
+        err.get("message", "request failed"),
+        type=err.get("type"),
+        code=err.get("code"),
+        status_code=status_code,
+        details=err.get("details"),
+        request_id=err.get("request_id"),
+    )

mailwire_sdk-0.1.1/src/mailwire_sdk/mcp_server.py

@@ -0,0 +1,278 @@
+"""mailwire MCP server (stdio transport).
+
+Exposes the inbox + message read/write surface as MCP tools so an AI agent host
+(Claude Desktop, IDE extensions, etc.) can drive mailwire on a user's behalf.
+
+Run via the `mailwire-mcp` console script:
+
+    MAILWIRE_BASE_URL=https://api.example.com \\
+    MAILWIRE_TOKEN=mw_live_... \\
+    mailwire-mcp
+
+Or wire it into an MCP host config:
+
+    {
+      "mcpServers": {
+        "mailwire": {
+          "command": "mailwire-mcp",
+          "env": {
+            "MAILWIRE_BASE_URL": "https://api.example.com",
+            "MAILWIRE_TOKEN": "mw_live_..."
+          }
+        }
+      }
+    }
+
+The server is intentionally thin — every tool is a direct passthrough to the
+SDK with the response JSON-encoded back to the caller. No business logic lives
+here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import sys
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from mailwire_sdk import Client, MailwireError
+
+_TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "mailwire_list_inboxes",
+        "description": (
+            "List inboxes for the authenticated tenant. Optionally filter by "
+            "workspace_id or project_id. Returns a JSON array of inbox objects "
+            "with their addresses inlined."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "workspace_id": {"type": "string"},
+                "project_id": {"type": "string"},
+                "limit": {"type": "integer", "default": 50, "maximum": 200},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_get_inbox",
+        "description": "Fetch a single inbox by its public ID (inb_*).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"inbox_id": {"type": "string"}},
+            "required": ["inbox_id"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_send_message",
+        "description": (
+            "Send an outbound email. `from_address` may be bare "
+            "(`name@domain`) or display-name form (`Name <name@domain>`). "
+            "Provide `text` or `html` (or both). Pass `idempotency_key` if "
+            "you want safe retries."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "inbox_id": {"type": "string"},
+                "from_address": {"type": "string"},
+                "to": {"type": "array", "items": {"type": "string"}, "minItems": 1},
+                "cc": {"type": "array", "items": {"type": "string"}},
+                "bcc": {"type": "array", "items": {"type": "string"}},
+                "subject": {"type": "string"},
+                "text": {"type": "string"},
+                "html": {"type": "string"},
+                "sending_domain_id": {"type": "string"},
+                "tags": {"type": "array", "items": {"type": "string"}},
+                "metadata": {"type": "object", "additionalProperties": {"type": "string"}},
+                "idempotency_key": {"type": "string"},
+            },
+            "required": ["inbox_id", "from_address", "to"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_list_messages",
+        "description": (
+            "List recent messages for the tenant. Filter by inbox_id, "
+            "thread_id, or direction (`outbound` / `inbound`)."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "inbox_id": {"type": "string"},
+                "thread_id": {"type": "string"},
+                "direction": {"type": "string", "enum": ["inbound", "outbound"]},
+                "limit": {"type": "integer", "default": 50, "maximum": 200},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_get_message",
+        "description": "Fetch a single message by its public ID (msg_*).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"message_id": {"type": "string"}},
+            "required": ["message_id"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_list_webhooks",
+        "description": (
+            "List active webhook subscribers for the tenant. Each entry "
+            "carries the URL, events_subscribed, secret_prefix, and "
+            "last delivery status."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_register_webhook",
+        "description": (
+            "Register a new webhook subscriber. Returns the plaintext signing "
+            "secret EXACTLY ONCE — record it on the subscriber side."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "url": {"type": "string"},
+                "events_subscribed": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "minItems": 1,
+                },
+                "environment": {"type": "string", "enum": ["live", "test"]},
+                "description": {"type": "string"},
+            },
+            "required": ["name", "url", "events_subscribed"],
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "mailwire_get_webhook_deliveries",
+        "description": (
+            "Fetch the most recent delivery attempts for a webhook subscriber "
+            "(useful for debugging why an event didn't arrive)."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {"endpoint_id": {"type": "string"}},
+            "required": ["endpoint_id"],
+            "additionalProperties": False,
+        },
+    },
+]
+
+
+def _dispatch(client: Client, name: str, args: dict[str, Any]) -> Any:  # noqa: PLR0911 — pure dispatch table
+    """Call the right SDK method for `name` and return the raw response."""
+    if name == "mailwire_list_inboxes":
+        return client.inboxes.list(
+            workspace_id=args.get("workspace_id"),
+            project_id=args.get("project_id"),
+            limit=args.get("limit", 50),
+        )
+    if name == "mailwire_get_inbox":
+        return client.inboxes.get(args["inbox_id"])
+    if name == "mailwire_send_message":
+        return client.messages.send(
+            inbox_id=args["inbox_id"],
+            from_address=args["from_address"],
+            to=args["to"],
+            cc=args.get("cc"),
+            bcc=args.get("bcc"),
+            subject=args.get("subject", ""),
+            text=args.get("text"),
+            html=args.get("html"),
+            sending_domain_id=args.get("sending_domain_id"),
+            tags=args.get("tags"),
+            metadata=args.get("metadata"),
+            idempotency_key=args.get("idempotency_key"),
+        )
+    if name == "mailwire_list_messages":
+        return client.messages.list(
+            inbox_id=args.get("inbox_id"),
+            thread_id=args.get("thread_id"),
+            direction=args.get("direction"),
+            limit=args.get("limit", 50),
+        )
+    if name == "mailwire_get_message":
+        return client.messages.get(args["message_id"])
+    if name == "mailwire_list_webhooks":
+        return client.webhooks.list()
+    if name == "mailwire_register_webhook":
+        return client.webhooks.create(
+            name=args["name"],
+            url=args["url"],
+            events_subscribed=args["events_subscribed"],
+            environment=args.get("environment", "live"),
+            description=args.get("description"),
+        )
+    if name == "mailwire_get_webhook_deliveries":
+        return client.webhooks.deliveries(args["endpoint_id"])
+    raise ValueError(f"unknown tool: {name}")
+
+
+async def _run() -> None:
+    base_url = os.environ.get("MAILWIRE_BASE_URL", "http://localhost:8083")
+    token = os.environ.get("MAILWIRE_TOKEN")
+    if not token:
+        print(
+            "MAILWIRE_TOKEN env var is required to run the mailwire MCP server",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    client = Client(token=token, base_url=base_url)
+    server: Server = Server("mailwire")
+
+    @server.list_tools()  # type: ignore[no-untyped-call,untyped-decorator]
+    async def _list() -> list[Tool]:
+        return [Tool(**spec) for spec in _TOOLS]
+
+    @server.call_tool()  # type: ignore[untyped-decorator]
+    async def _call(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        try:
+            result = await asyncio.to_thread(_dispatch, client, name, arguments or {})
+        except MailwireError as exc:
+            payload = {
+                "ok": False,
+                "error": {
+                    "type": exc.type,
+                    "code": exc.code,
+                    "message": str(exc),
+                    "details": exc.details,
+                    "request_id": exc.request_id,
+                },
+            }
+            return [TextContent(type="text", text=json.dumps(payload, indent=2))]
+        return [TextContent(type="text", text=json.dumps(result, indent=2, default=str))]
+
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+    client.close()
+
+
+def main() -> None:
+    """Console entry point — `mailwire-mcp`."""
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/__init__.py

@@ -0,0 +1,19 @@
+"""Per-resource SDK clients."""
+
+from mailwire_sdk.resources.api_keys import ApiKeysResource
+from mailwire_sdk.resources.domains import DomainsResource
+from mailwire_sdk.resources.inboxes import InboxesResource
+from mailwire_sdk.resources.messages import MessagesResource
+from mailwire_sdk.resources.tenants import TenantsResource
+from mailwire_sdk.resources.threads import ThreadsResource
+from mailwire_sdk.resources.webhooks import WebhooksResource
+
+__all__ = [
+    "ApiKeysResource",
+    "DomainsResource",
+    "InboxesResource",
+    "MessagesResource",
+    "TenantsResource",
+    "ThreadsResource",
+    "WebhooksResource",
+]

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/api_keys.py

@@ -0,0 +1,55 @@
+"""API-key CRUD under `/v1/tenants/{t}/api_keys` — admin-scoped.
+
+The mint response includes a `token` field exactly once. Surface it to the user
+immediately; the server keeps only an Argon2id hash.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class ApiKeysResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self,
+        tenant_id: str,
+        *,
+        name: str,
+        scopes: list[str],
+        environment: str = "live",
+        workspace_id: str | None = None,
+        project_id: str | None = None,
+        inbox_id: str | None = None,
+        expires_at: datetime | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "name": name,
+            "scopes": scopes,
+            "environment": environment,
+            "metadata": metadata or {},
+        }
+        if workspace_id is not None:
+            body["workspace_id"] = workspace_id
+        if project_id is not None:
+            body["project_id"] = project_id
+        if inbox_id is not None:
+            body["inbox_id"] = inbox_id
+        if expires_at is not None:
+            body["expires_at"] = expires_at.isoformat()
+        return self._t.request("POST", f"/v1/tenants/{tenant_id}/api_keys", json=body)
+
+    def list(self, tenant_id: str) -> list[dict[str, Any]]:
+        return self._t.request("GET", f"/v1/tenants/{tenant_id}/api_keys")["data"]  # type: ignore[no-any-return]
+
+    def get(self, tenant_id: str, key_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/tenants/{tenant_id}/api_keys/{key_id}")
+
+    def revoke(self, tenant_id: str, key_id: str) -> None:
+        self._t.request("DELETE", f"/v1/tenants/{tenant_id}/api_keys/{key_id}")

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/domains.py

@@ -0,0 +1,44 @@
+"""Domain registration + verification."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class DomainsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def register(
+        self,
+        tenant_id: str,
+        *,
+        domain_name: str,
+        purpose: str,
+        region: str = "us",
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body = {
+            "domain_name": domain_name,
+            "purpose": purpose,
+            "region": region,
+            "metadata": metadata or {},
+        }
+        return self._t.request("POST", f"/v1/tenants/{tenant_id}/domains", json=body)
+
+    def list_for_tenant(self, tenant_id: str) -> list[dict[str, Any]]:
+        return self._t.request("GET", f"/v1/tenants/{tenant_id}/domains")["data"]  # type: ignore[no-any-return]
+
+    def get(self, domain_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/domains/{domain_id}")
+
+    def get_dns_records(self, domain_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/domains/{domain_id}/dns_records")
+
+    def verify(self, domain_id: str) -> dict[str, Any]:
+        return self._t.request("POST", f"/v1/domains/{domain_id}/verify")
+
+    def delete(self, domain_id: str) -> None:
+        self._t.request("DELETE", f"/v1/domains/{domain_id}")

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/inboxes.py

@@ -0,0 +1,81 @@
+"""Inbox + address management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class InboxesResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self,
+        *,
+        client_id: str,
+        display_name: str,
+        domain_id: str,
+        shareable_local_part: str | None = None,
+        private_address_count: int = 0,
+        workspace_id: str | None = None,
+        project_id: str | None = None,
+        signature_text: str | None = None,
+        signature_html: str | None = None,
+        timezone: str = "UTC",
+        language: str = "en",
+        avatar_url: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "client_id": client_id,
+            "display_name": display_name,
+            "domain_id": domain_id,
+            "private_address_count": private_address_count,
+            "timezone": timezone,
+            "language": language,
+            "metadata": metadata or {},
+        }
+        if shareable_local_part is not None:
+            body["shareable_address"] = {"local_part": shareable_local_part}
+        for k, v in (
+            ("workspace_id", workspace_id),
+            ("project_id", project_id),
+            ("signature_text", signature_text),
+            ("signature_html", signature_html),
+            ("avatar_url", avatar_url),
+        ):
+            if v is not None:
+                body[k] = v
+        return self._t.request("POST", "/v1/inboxes", json=body)
+
+    def list(
+        self,
+        *,
+        workspace_id: str | None = None,
+        project_id: str | None = None,
+        limit: int = 50,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        if workspace_id is not None:
+            params["workspace_id"] = workspace_id
+        if project_id is not None:
+            params["project_id"] = project_id
+        return self._t.request("GET", "/v1/inboxes", params=params)["data"]  # type: ignore[no-any-return]
+
+    def get(self, inbox_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/inboxes/{inbox_id}")
+
+    def update(
+        self,
+        inbox_id: str,
+        **fields: Any,
+    ) -> dict[str, Any]:
+        return self._t.request("PATCH", f"/v1/inboxes/{inbox_id}", json=fields)
+
+    def archive(self, inbox_id: str) -> None:
+        self._t.request("DELETE", f"/v1/inboxes/{inbox_id}")
+
+    def add_address(self, inbox_id: str) -> dict[str, Any]:
+        return self._t.request("POST", f"/v1/inboxes/{inbox_id}/addresses")

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/messages.py

@@ -0,0 +1,78 @@
+"""Outbound + read endpoints for messages."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class MessagesResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def send(
+        self,
+        *,
+        inbox_id: str,
+        from_address: str,
+        to: list[str],
+        subject: str = "",
+        text: str | None = None,
+        html: str | None = None,
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None,
+        sending_domain_id: str | None = None,
+        in_reply_to_message_id: str | None = None,
+        headers: dict[str, str] | None = None,
+        attachments: list[dict[str, Any]] | None = None,
+        tags: list[str] | None = None,
+        tracking_opens: bool = False,
+        tracking_clicks: bool = False,
+        metadata: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "inbox_id": inbox_id,
+            "from_address": from_address,
+            "to": to,
+            "cc": cc or [],
+            "bcc": bcc or [],
+            "subject": subject,
+            "headers": headers or {},
+            "attachments": attachments or [],
+            "tags": tags or [],
+            "tracking": {"opens": tracking_opens, "clicks": tracking_clicks},
+            "metadata": metadata or {},
+        }
+        if sending_domain_id is not None:
+            body["sending_domain_id"] = sending_domain_id
+        if in_reply_to_message_id is not None:
+            body["in_reply_to_message_id"] = in_reply_to_message_id
+        if text is not None:
+            body["text"] = text
+        if html is not None:
+            body["html"] = html
+        request_headers = (
+            {"Idempotency-Key": idempotency_key} if idempotency_key is not None else None
+        )
+        return self._t.request(
+            "POST", "/v1/messages", json=body, headers=request_headers
+        )
+
+    def list(
+        self,
+        *,
+        inbox_id: str | None = None,
+        thread_id: str | None = None,
+        direction: str | None = None,
+        limit: int = 50,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        for k, v in (("inbox_id", inbox_id), ("thread_id", thread_id), ("direction", direction)):
+            if v is not None:
+                params[k] = v
+        return self._t.request("GET", "/v1/messages", params=params)["data"]  # type: ignore[no-any-return]
+
+    def get(self, message_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/messages/{message_id}")

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/tenants.py

@@ -0,0 +1,48 @@
+"""Tenant CRUD — admin-scoped."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class TenantsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self,
+        *,
+        name: str,
+        slug: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name, "metadata": metadata or {}}
+        if slug is not None:
+            body["slug"] = slug
+        return self._t.request("POST", "/v1/tenants", json=body)
+
+    def list(self, *, limit: int = 50) -> list[dict[str, Any]]:
+        return self._t.request("GET", "/v1/tenants", params={"limit": limit})["data"]  # type: ignore[no-any-return]
+
+    def get(self, tenant_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/tenants/{tenant_id}")
+
+    def update(
+        self,
+        tenant_id: str,
+        *,
+        name: str | None = None,
+        status: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body = {
+            k: v
+            for k, v in (("name", name), ("status", status), ("metadata", metadata))
+            if v is not None
+        }
+        return self._t.request("PATCH", f"/v1/tenants/{tenant_id}", json=body)
+
+    def delete(self, tenant_id: str) -> None:
+        self._t.request("DELETE", f"/v1/tenants/{tenant_id}")

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/threads.py

@@ -0,0 +1,35 @@
+"""Thread list / detail — `/v1/threads`. Gmail-style inbox view."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class ThreadsResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def get(
+        self, thread_id: str, *, include_last_message: bool = True
+    ) -> dict[str, Any]:
+        params = {"include_last_message": "true" if include_last_message else "false"}
+        return self._t.request("GET", f"/v1/threads/{thread_id}", params=params)
+
+    # `list` defined LAST so other annotations bind to the builtin
+    # (Python class scope is built top-down).
+    def list(
+        self,
+        *,
+        inbox_id: str,
+        limit: int = 50,
+        include_last_message: bool = True,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {
+            "inbox_id": inbox_id,
+            "limit": limit,
+            "include_last_message": "true" if include_last_message else "false",
+        }
+        data = self._t.request("GET", "/v1/threads", params=params).get("data", [])
+        return list(data)

mailwire_sdk-0.1.1/src/mailwire_sdk/resources/webhooks.py

@@ -0,0 +1,85 @@
+"""Webhook subscriber CRUD — `/v1/webhooks`.
+
+The `secret` field is returned EXACTLY ONCE on `create` and `rotate_secret`.
+Listings + reads expose only `secret_prefix`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mailwire_sdk._transport import Transport
+
+
+class WebhooksResource:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self,
+        *,
+        name: str,
+        url: str,
+        events_subscribed: list[str],
+        environment: str = "live",
+        workspace_id: str | None = None,
+        description: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "name": name,
+            "url": url,
+            "events_subscribed": events_subscribed,
+            "environment": environment,
+            "metadata": metadata or {},
+        }
+        if workspace_id is not None:
+            body["workspace_id"] = workspace_id
+        if description is not None:
+            body["description"] = description
+        return self._t.request("POST", "/v1/webhooks", json=body)
+
+    def get(self, endpoint_id: str) -> dict[str, Any]:
+        return self._t.request("GET", f"/v1/webhooks/{endpoint_id}")
+
+    def update(
+        self,
+        endpoint_id: str,
+        *,
+        url: str | None = None,
+        events_subscribed: list[str] | None = None,
+        enabled: bool | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if url is not None:
+            body["url"] = url
+        if events_subscribed is not None:
+            body["events_subscribed"] = events_subscribed
+        if enabled is not None:
+            body["enabled"] = enabled
+        if description is not None:
+            body["description"] = description
+        return self._t.request("PATCH", f"/v1/webhooks/{endpoint_id}", json=body)
+
+    def revoke(self, endpoint_id: str) -> None:
+        self._t.request("DELETE", f"/v1/webhooks/{endpoint_id}")
+
+    def rotate_secret(self, endpoint_id: str) -> dict[str, Any]:
+        return self._t.request("POST", f"/v1/webhooks/{endpoint_id}/rotate_secret")
+
+    def deliveries(
+        self, endpoint_id: str, *, limit: int = 50
+    ) -> list[dict[str, Any]]:
+        data = self._t.request(
+            "GET",
+            f"/v1/webhooks/{endpoint_id}/deliveries",
+            params={"limit": limit},
+        ).get("data", [])
+        return list(data)
+
+    # `list` is defined LAST so other methods' `list[...]` annotations bind
+    # to the builtin (Python class scope is built top-down).
+    def list(self) -> list[dict[str, Any]]:
+        data = self._t.request("GET", "/v1/webhooks").get("data", [])
+        return list(data)