maily-client

Fast, fully-typed async & sync Python SDK for the maily multi-provider temporary email platform.

Built for integration tests (Pytest, Playwright, Selenium, Cypress), automation bots, and QA verification pipelines. Features 1-line disposable mailbox creation, automatic OTP verification code extraction via regex, magic activation link parsing, real-time message streaming, and resilient networking.

🔗 Quick Links

• 📖 Documentation & Guides: https://stormsia.github.io/maily/
• 🚀 Server Package (PyPI): https://pypi.org/project/maily-server/
• 📦 Client Package (PyPI): https://pypi.org/project/maily-client/
• 🐙 GitHub Repository: https://github.com/stormsia/maily
• 🐛 Issue Tracker: https://github.com/stormsia/maily/issues
• 📝 Changelog: https://github.com/stormsia/maily/blob/main/CHANGELOG.md

✨ Key Features

• Standard Import (maily_client): Clean, conflict-free Python imports (from maily_client import Maily, SyncMaily).
• Single-File Portability: Ships as a lightweight client requiring only httpx, loguru, and pydantic. Zero heavy dependencies.
• Fully Typed (PEP 561): 100% type annotations with py.typed compliance and Pydantic response models for rich IDE autocompletion.
• Async & Sync Support: Native async/await (Maily) with high-concurrency polling, plus a lightweight synchronous facade (SyncMaily) for traditional test suites.
• Magic Verification Extraction: Built-in polling and regex extraction for OTP verification codes (wait_for_code) and account activation links (wait_for_link).
• Resilient Networking: Optional exponential backoff retry policy handling transient errors (HTTP 502/504, connection timeouts) and honoring HTTP 429 Retry-After.
• Self-Updating CLI: Built-in CLI tool maily-client to check for and apply updates directly from git.

📦 Installation & Import

Preferred — via PyPI:

pip install maily-client

Import in Python:

from maily_client import Maily, SyncMaily, WaitTimeoutError

Alternative 1: Direct from GitHub:

pip install "maily-client @ git+https://github.com/stormsia/maily.git#subdirectory=client"

Alternative 2: Standalone Single-File Download (Zero Install)

Because the client has no internal server dependencies, you can download maily_client.py directly into your project:

# Linux / macOS
curl -O https://raw.githubusercontent.com/stormsia/maily/main/client/maily_client.py

# Windows PowerShell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/stormsia/maily/main/client/maily_client.py" -OutFile "maily_client.py"

Dependencies for standalone use:

pip install httpx loguru pydantic

⚠️ Important: Attribute Access vs Dictionary Key Access

CRITICAL RULE: In maily-client, native dot/attribute access is supported ONLY on Pydantic models and specifically ExtractedConfirmation (which implements Mapping and allows dual access: both res.confirmation_code and res["confirmation_code"]).

All other client methods returning standard Python dictionaries (such as await api.config.get(), sync_api.config.get(), or raw response dicts) DO NOT support attribute/dot access. You MUST access dictionary values using standard bracket key indexing (d["key"]), NEVER dot syntax (d.key).

# 1. ExtractedConfirmation (Pydantic model implementing Mapping) supports BOTH:
res = await api.wait_for_confirmation_email(box, digit_code_mask=r"\b(\d{6})\b")
if res is not None:
    # ✅ Attribute / dot access:
    print(res.subject)
    print(res.confirmation_code)
    print(res.confirmation_link)
    print(res.message_id)
    print(res.from_address)

    # ✅ Dictionary mapping access:
    print(res["confirmation_code"])
    print(res["confirmation_link"])
    print(res["subject"])

# 2. Standard dictionary responses (e.g., api.config.get()):
cfg = await api.config.get()
print(cfg["client_version"])  # ✅ CORRECT: standard dictionary indexing
# print(cfg.client_version)   # ❌ ERROR: AttributeError ('dict' object has no attribute 'client_version')

🚀 Quickstart

1-Line Mailbox & Verification Code Extraction

import asyncio

# Preferred when using maily-client SDK:
from maily_client import Maily, WaitTimeoutError
# (Or if using the maily-server package directly: from maily import Maily, WaitTimeoutError)


async def main():
    async with Maily("http://127.0.0.1:8477", api_key="your_secret_api_key") as api:
        # Create a disposable mailbox with automatic domain selection
        box = await api.create_temp_mailbox()
        print(f"Disposable email: {box.address}")

        # Send an email to box.address, then wait for the code:
        try:
            code = await api.wait_for_code(box, timeout=60.0)
            print(f"Received verification code: {code}")
        except WaitTimeoutError:
            print("Timed out waiting for email.")


asyncio.run(main())

Confirmation Extraction (ExtractedConfirmation Dual Access)

async with Maily("http://127.0.0.1:8477") as api:
    box = await api.create_temp_mailbox()

    # Wait for email and extract both verification code and activation link
    res = await api.wait_for_confirmation_email(box, digit_code_mask=r"\b(\d{6})\b")
    if res is not None:
        # 1. Attribute / dot access:
        print(f"Subject: {res.subject}")
        print(f"Code: {res.confirmation_code}")

        # 2. Key mapping access:
        print(f"Link: {res['confirmation_link']}")
        print(f"Code: {res['confirmation_code']}")

Synchronous Client (SyncMaily)

# Standalone client:
from maily_client import SyncMaily
# Or via server package: from maily import SyncMaily

with SyncMaily("http://127.0.0.1:8477", api_key="your_secret_api_key") as api:
    box = api.create_temp_mailbox()
    code = api.wait_for_code(box, timeout=45.0)
    print(f"Received code synchronously: {code}")

Confirmation Link Extraction

async with Maily("http://127.0.0.1:8477") as api:
    box = await api.create_temp_mailbox(provider="tempmail.plus")
    print(f"Address: {box.address}")

    # Automatically extracts URLs containing 'confirm', 'verify', or 'activate'
    link = await api.wait_for_link(box, timeout=90.0)
    print(f"Confirmation URL: {link}")

Real-Time Email Streaming (Async Iterator)

async with Maily("http://127.0.0.1:8477") as api:
    box = await api.mailboxes.create(domain="mail.tm")

    # Continuously yields new messages as they arrive
    async for msg in api.messages.iter_messages(box, poll_interval=2.0, timeout=120.0):
        print(f"Incoming: {msg.subject} from {msg.from_address}")
        detail = await api.messages.get(box, msg.message_api_id)
        print("Body text:\n", detail.text)

Granular Exception Handling

All API errors inherit from ApiError, which inherits from ClientError:

from maily_client import (
    AuthenticationError,  # 401: Invalid API key
    ForbiddenError,  # 403: Scope denied
    NotFoundError,  # 404: Mailbox or message missing
    ValidationError,  # 422 / 400: Bad params
    RateLimitError,  # 429: Rate limited
    UpstreamProviderError,  # 502/504: Provider downtime
    WaitTimeoutError,  # Timeout waiting for email/code
)

try:
    detail = await api.messages.get(box, "unknown_id")
except NotFoundError:
    print("Message not found!")
except AuthenticationError:
    print("Check your API key!")

Scoped API Key Management

async with Maily("http://127.0.0.1:8477", api_key="root_secret") as api:
    # Create key restricted to mail.tm only
    new_key = await api.keys.create(
        name="bot-worker",
        scope={"providers": ["mail.tm"], "parent_ids": [], "actions": ["read", "write"]},
    )
    print(f"Key Prefix: {new_key.prefix} | Secret: {new_key.secret}")

Retention & Database Maintenance

async with Maily("http://127.0.0.1:8477", api_key="root_secret") as api:
    # Run regular retention sweep (triggers DB maintenance if interval has elapsed)
    res = await api.admin.retention_run()
    print(f"Deleted: {res.mailboxes_deleted} boxes, {res.messages_deleted} messages")

    # Or force immediate full database maintenance (VACUUM, REINDEX, ANALYZE):
    res = await api.admin.retention_run(force_maintenance=True)

🛠️ API Overview & Structure

Maily exposes organized domain resource sections as well as top-level flat convenience methods:

Resource Sections

⚡ Flat Facade Shortcut Methods

Both Maily (async) and SyncMaily (sync) provide direct top-level facade shortcuts for rapid automation. All 19 flat shortcut methods forward directly to their respective section implementations:

Additional Root Convenience Methods

• create_temp_mailbox(*, provider: str | None = None, domain: str | None = None) -> Mailbox — Instantly creates a temporary mailbox, automatically selecting the best available active domain if omitted.
• wait_for_code(mailbox_id, *, pattern=r"\b(\d{4,8})\b", sender_domain=None, timeout=60.0, check_interval=3.0) -> str — Polls for incoming email and returns the extracted digit verification code (raises WaitTimeoutError on timeout).
• wait_for_link(mailbox_id, *, url_contain=None, sender_domain=None, timeout=60.0, check_interval=3.0) -> str — Polls for incoming email and returns the matching activation URL (raises WaitTimeoutError on timeout).
• wait_for_confirmation_email(mailbox_id, *, sender_domain=None, url_contain=None, digit_code_mask=None, timeout=60.0, check_interval=5.0) -> ExtractedConfirmation | None — High-level extractor returning ExtractedConfirmation (supports dot and dict access) or None on timeout.
• check_client_version() -> str — Queries /v1/config and logs a warning via Loguru if the client version does not match the server.

💻 CLI Commands

The package includes a command-line interface executable as maily-client (or via python -m maily_client):

# Display help and usage
maily-client --help

# Show current installed client version
maily-client version

# Check GitHub repository for newer version (exit codes: 0=up-to-date, 2=update available, 1=network error)
maily-client check

# Download and replace local client file with latest release from GitHub
maily-client update

CLI Exit Codes

Environment Variables

• MAILY_CLIENT_SOURCE: URL to fetch the canonical client from when checking or updating (defaults to GitHub main branch raw file: https://raw.githubusercontent.com/stormsia/maily/main/client/maily_client.py).

🛡️ Error Handling & Resiliency

The client provides explicit exceptions inheriting from ClientError:

ClientError
 ├── WaitTimeoutError
 └── ApiError
      ├── AuthenticationError   (HTTP 401: Invalid API key or missing Authorization header)
      ├── ForbiddenError        (HTTP 403: Scoped API key does not have permission)
      ├── NotFoundError         (HTTP 404: Mailbox or message does not exist)
      ├── ValidationError       (HTTP 422: Malformed input or schema validation failure)
      ├── RateLimitError        (HTTP 429: Rate limited by server or upstream provider)
      └── UpstreamProviderError (HTTP 502 / 504: Upstream temporary mail provider failure)

HTTP 422 Validation Error Formatting

FastAPI validation errors returning a list of field error objects ([{"loc": ["body", "domain"], "msg": "..."}]) are automatically formatted into readable messages:

from maily_client import Maily, ValidationError

async with Maily("http://127.0.0.1:8477") as api:
    try:
        # Invalid input parameters
        await api.mailboxes.create(domain="invalid domain!@#")
    except ValidationError as exc:
        print(f"Status Code: {exc.status_code}")  # 422
        # Clean formatted string: "body -> domain: Value error, invalid domain name characters"
        print(f"Validation Detail: {exc.detail}")

HTTP 429 Rate Limiting & Automatic Retries

When max_retries > 0, the client automatically honors HTTP 429 Retry-After headers and applies exponential backoff for transient HTTP 502/504 errors and network connection timeouts:

from maily_client import Maily, RateLimitError

# Configure client-side retry policy
api = Maily(
    "http://127.0.0.1:8477",
    max_retries=3,  # Retry up to 3 times before raising
    retry_backoff=0.5,  # Base backoff in seconds (0.5s, 1.0s, 2.0s)
)

try:
    box = await api.create_temp_mailbox()
except RateLimitError as exc:
    # If retries are exhausted or max_retries is 0
    print(f"Rate limited (HTTP 429). Server message: {exc.detail}")

📄 License

This project is licensed under the MIT License.