mailwire-sdk 0.1.3

Python SDK for mailwire-x1

mailwire-sdk

Python SDK for mailwire-x1.

Install

pip install mailwire-sdk

To also install the MCP server entry point:

pip install 'mailwire-sdk[mcp]'

Usage

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 <[e-mail]>",
        to=["[e-mail]"],
        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:

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:

{
  "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 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.