Metadata-Version: 2.4
Name: mailwire-sdk
Version: 0.1.4
Summary: Python SDK for mailwire-x1
Requires-Python: >=3.9
Requires-Dist: httpx<0.28,>=0.27
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# 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.
