mm-async

Async HTTP client for Mattermost API with High-Level API support.

Features

• Async/await with httpx
• High-Level API — client.users, client.teams, client.channels, client.posts
• Type-safe — Pydantic models for all responses
• Resilient — automatic retry with exponential backoff
• Rate limit aware — respects Retry-After headers
• Secure — SecretStr for token storage, SSL verification warnings

Installation

pip install mm-async

Or with Poetry:

poetry add mm-async

Quick Start

from mm_async import AsyncMattermostClient

async def main():
    async with AsyncMattermostClient(
        url="https://mattermost.example.com",
        token="your-bot-token",
    ) as client:
        # Get current user
        me = await client.users.get_me()
        print(f"Bot: {me.username}")

        # Search users
        users = await client.users.search("john")

        # Send message
        post = await client.posts.create(
            channel_id="abc123",
            message="Hello from bot!"
        )

        # Create DM and send message
        dm = await client.channels.create_direct([me.id, users[0].id])
        await client.posts.create(dm.id, "Private message")

Configuration

High-Level API

See API Reference for complete method documentation.

Error Handling

from mm_async import (
    AsyncMattermostClient,
    MattermostAuthError,
    MattermostRateLimitError,
    MattermostNotFoundError,
)

async with AsyncMattermostClient(url=url, token=token) as client:
    try:
        user = await client.users.get_by_username("john")
        if user is None:
            print("User not found")
    except MattermostAuthError:
        print("Invalid token")
    except MattermostRateLimitError as e:
        print(f"Rate limited, retry after {e.retry_after}s")

Retry Logic

• GET, DELETE — automatic retry with exponential backoff
• POST, PUT — no retry (to avoid duplicates)
• Retries on: 500, 502, 503, 504, 429 status codes
• Respects Retry-After header for rate limits

Exceptions

Documentation

• API Reference — Complete API documentation
• Examples — Practical usage examples

Requirements

• Python 3.11+
• httpx >= 0.28.0
• pydantic >= 2.0.0

License

MIT