mailfixture 0.1.0__tar.gz

mailfixture-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.egg-info/
+dist/

mailfixture-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailFixture, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailfixture-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: mailfixture
+Version: 0.1.0
+Summary: Email fixtures for your test suite — programmatic inboxes, long-polling, first-class OTP and link extraction.
+Project-URL: Homepage, https://mailfixture.com
+Project-URL: Documentation, https://mailfixture.com/docs
+Author-email: MailFixture <support@mailfixture.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e2e,email,fixtures,otp,playwright,pytest,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# mailfixture
+
+Email fixtures for your test suite. Create a programmatic inbox in one call,
+point your app's signup / OTP / password-reset flow at it, then wait for the
+email — parsed, with the OTP and links already extracted.
+
+Receive-only, built for CI: long-polling instead of retry loops, zero
+dependencies outside the Python standard library, Python 3.9+.
+
+```bash
+pip install mailfixture
+```
+
+## Quickstart
+
+Create a key in [Dashboard → API keys](https://mailfixture.com/app/keys) and
+export it as `MAILFIXTURE_API_KEY`.
+
+```python
+from mailfixture import MailFixture
+
+mfx = MailFixture()  # reads MAILFIXTURE_API_KEY
+
+def test_signup_sends_otp(page):
+    inbox = mfx.create_inbox(ttl_seconds=900)
+
+    page.goto("/signup")
+    page.fill("#email", inbox.email_address)
+    page.click("text=Send code")
+
+    otp = inbox.wait_for_otp(timeout=30)   # long-polls; no sleep()
+    page.fill("#otp", otp)
+```
+
+Waiting for a magic link instead:
+
+```python
+link = inbox.wait_for_link(kind="verify", timeout=30)
+page.goto(link.url)
+```
+
+Everything on the wait helpers is server-side long-polling: the request is
+held open until a matching message arrives (or the timeout passes, raising
+`mailfixture.MailFixtureTimeout`).
+
+## API surface
+
+| Method | Purpose |
+| --- | --- |
+| `create_inbox(local_part=, domain=, ttl_seconds=)` | new inbox; returns an `Inbox` handle |
+| `inbox.wait_for_message(match=, timeout=)` | first matching message, full body + extraction |
+| `inbox.wait_for_otp(match=, timeout=)` | best extracted OTP as a string |
+| `inbox.wait_for_link(kind=, match=, timeout=)` | first link, optionally `verify\|reset\|unsubscribe` |
+| `inbox.messages(since=, match=, wait=)` / `clear()` / `delete()` | raw listing & lifecycle |
+| `get_message(id)`, `get_otp(id)`, `get_links(id)` | direct message access |
+| `download_attachment(message_id, index)` | decoded attachment bytes |
+| `create_domain(fqdn)`, `verify_domain(id)`, `list_domains()`, `delete_domain(id)` | custom domains |
+| `create_key(label=)`, `list_keys()`, `revoke_key(id)` | API keys |
+
+`match` filters with `subject:`, `from:`, or `to:` prefixes; a bare term
+matches the subject.
+
+Errors are raised as `mailfixture.MailFixtureError` carrying the API's
+RFC 7807 `status` / `title` / `detail` fields.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+Docs: https://mailfixture.com/docs

mailfixture-0.1.0/README.md

@@ -0,0 +1,72 @@
+# mailfixture
+
+Email fixtures for your test suite. Create a programmatic inbox in one call,
+point your app's signup / OTP / password-reset flow at it, then wait for the
+email — parsed, with the OTP and links already extracted.
+
+Receive-only, built for CI: long-polling instead of retry loops, zero
+dependencies outside the Python standard library, Python 3.9+.
+
+```bash
+pip install mailfixture
+```
+
+## Quickstart
+
+Create a key in [Dashboard → API keys](https://mailfixture.com/app/keys) and
+export it as `MAILFIXTURE_API_KEY`.
+
+```python
+from mailfixture import MailFixture
+
+mfx = MailFixture()  # reads MAILFIXTURE_API_KEY
+
+def test_signup_sends_otp(page):
+    inbox = mfx.create_inbox(ttl_seconds=900)
+
+    page.goto("/signup")
+    page.fill("#email", inbox.email_address)
+    page.click("text=Send code")
+
+    otp = inbox.wait_for_otp(timeout=30)   # long-polls; no sleep()
+    page.fill("#otp", otp)
+```
+
+Waiting for a magic link instead:
+
+```python
+link = inbox.wait_for_link(kind="verify", timeout=30)
+page.goto(link.url)
+```
+
+Everything on the wait helpers is server-side long-polling: the request is
+held open until a matching message arrives (or the timeout passes, raising
+`mailfixture.MailFixtureTimeout`).
+
+## API surface
+
+| Method | Purpose |
+| --- | --- |
+| `create_inbox(local_part=, domain=, ttl_seconds=)` | new inbox; returns an `Inbox` handle |
+| `inbox.wait_for_message(match=, timeout=)` | first matching message, full body + extraction |
+| `inbox.wait_for_otp(match=, timeout=)` | best extracted OTP as a string |
+| `inbox.wait_for_link(kind=, match=, timeout=)` | first link, optionally `verify\|reset\|unsubscribe` |
+| `inbox.messages(since=, match=, wait=)` / `clear()` / `delete()` | raw listing & lifecycle |
+| `get_message(id)`, `get_otp(id)`, `get_links(id)` | direct message access |
+| `download_attachment(message_id, index)` | decoded attachment bytes |
+| `create_domain(fqdn)`, `verify_domain(id)`, `list_domains()`, `delete_domain(id)` | custom domains |
+| `create_key(label=)`, `list_keys()`, `revoke_key(id)` | API keys |
+
+`match` filters with `subject:`, `from:`, or `to:` prefixes; a bare term
+matches the subject.
+
+Errors are raised as `mailfixture.MailFixtureError` carrying the API's
+RFC 7807 `status` / `title` / `detail` fields.
+
+## Development
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests
+```
+
+Docs: https://mailfixture.com/docs

mailfixture-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailfixture"
+version = "0.1.0"
+description = "Email fixtures for your test suite — programmatic inboxes, long-polling, first-class OTP and link extraction."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "MailFixture", email = "support@mailfixture.com" }]
+keywords = ["email", "testing", "otp", "fixtures", "e2e", "playwright", "pytest"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://mailfixture.com"
+Documentation = "https://mailfixture.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailfixture"]

mailfixture-0.1.0/src/mailfixture/__init__.py

@@ -0,0 +1,801 @@
+"""MailFixture — email fixtures for your test suite.
+
+Create a programmatic inbox, point your app's signup/OTP/reset flow at it,
+then wait for the email and assert on the extracted OTP or link:
+
+    from mailfixture import MailFixture
+
+    mfx = MailFixture()  # reads MAILFIXTURE_API_KEY
+    inbox = mfx.create_inbox(ttl_seconds=900)
+    # ... drive your app to send mail to inbox.email_address ...
+    otp = inbox.wait_for_otp(timeout=30)
+
+The client is synchronous and has zero dependencies outside the standard
+library. Long-polling is done server-side (`wait=`), so there is no sleep
+to tune and no flaky retry loop.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import math
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+__all__ = [
+    "MailFixture",
+    "Inbox",
+    "InboxSummary",
+    "Message",
+    "MessageSummary",
+    "Otp",
+    "OtpCandidate",
+    "Link",
+    "Attachment",
+    "Domain",
+    "DomainVerification",
+    "ApiKey",
+    "CreatedApiKey",
+    "Webhook",
+    "CreatedWebhook",
+    "WebhookDelivery",
+    "verify_webhook_signature",
+    "MailFixtureError",
+    "MailFixtureTimeout",
+]
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.mailfixture.com"
+#: Server-side ceiling for one long-poll request; the client chains
+#: requests until its own deadline, so timeouts may exceed this.
+MAX_SERVER_WAIT = 60
+
+
+class MailFixtureError(Exception):
+    """An RFC 7807 problem+json error response from the API."""
+
+    def __init__(
+        self,
+        status: Optional[int],
+        title: str,
+        detail: Optional[str] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        self.status = status
+        self.title = title
+        self.detail = detail
+        self.retry_after = retry_after
+        message = f"{title} (HTTP {status})" if status else title
+        if detail:
+            message = f"{message}: {detail}"
+        super().__init__(message)
+
+
+class MailFixtureTimeout(MailFixtureError):
+    """No matching message arrived before the client-side deadline."""
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(None, "timed out", detail)
+
+
+def _parse_dt(value: str) -> datetime:
+    # Python < 3.11 fromisoformat rejects a trailing Z.
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    return datetime.fromisoformat(value)
+
+
+@dataclass
+class OtpCandidate:
+    value: str
+    score: float
+
+
+@dataclass
+class Otp:
+    """Ranked OTP candidates extracted from a message; `best` is the winner."""
+
+    best: Optional[str]
+    candidates: List[OtpCandidate]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Otp":
+        return cls(
+            best=data.get("best"),
+            candidates=[
+                OtpCandidate(value=c["value"], score=c["score"])
+                for c in data.get("candidates", [])
+            ],
+        )
+
+
+@dataclass
+class Link:
+    """A URL extracted from a message. `kind` is the server's guess:
+    verify | reset | unsubscribe | other (wire name: `class`)."""
+
+    url: str
+    text: Optional[str]
+    kind: str
+
+    def __str__(self) -> str:
+        return self.url
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Link":
+        return cls(url=data["url"], text=data.get("text"), kind=data.get("class", "other"))
+
+
+@dataclass
+class Attachment:
+    filename: str
+    content_type: str
+    size: int
+    inline: bool
+    index: int
+
+
+@dataclass
+class MessageSummary:
+    id: str
+    received_at: datetime
+    from_addr: str
+    to_addrs: List[str]
+    subject: Optional[str]
+    #: Wire-format timestamp, used verbatim as the next `since` cursor.
+    received_at_raw: str = field(repr=False, default="")
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "MessageSummary":
+        return cls(
+            id=data["id"],
+            received_at=_parse_dt(data["received_at"]),
+            from_addr=data["from_addr"],
+            to_addrs=list(data["to_addrs"]),
+            subject=data.get("subject"),
+            received_at_raw=data["received_at"],
+        )
+
+
+@dataclass
+class Message:
+    id: str
+    inbox_id: str
+    received_at: datetime
+    from_addr: str
+    to_addrs: List[str]
+    subject: Optional[str]
+    text_body: Optional[str]
+    html_body: Optional[str]
+    headers: Dict[str, Any]
+    extracted: Dict[str, Any]
+    attachments: List[Attachment]
+    raw_size: int
+    expires_at: datetime
+
+    @property
+    def otp(self) -> Optional[str]:
+        """The best extracted OTP, if any."""
+        return (self.extracted.get("otp") or {}).get("best")
+
+    @property
+    def links(self) -> List[Link]:
+        return [Link._from_json(l) for l in self.extracted.get("links", [])]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Message":
+        return cls(
+            id=data["id"],
+            inbox_id=data["inbox_id"],
+            received_at=_parse_dt(data["received_at"]),
+            from_addr=data["from_addr"],
+            to_addrs=list(data["to_addrs"]),
+            subject=data.get("subject"),
+            text_body=data.get("text_body"),
+            html_body=data.get("html_body"),
+            headers=data.get("headers") or {},
+            extracted=data.get("extracted") or {},
+            attachments=[
+                Attachment(
+                    filename=a.get("filename", ""),
+                    content_type=a.get("content_type", ""),
+                    size=a.get("size", 0),
+                    inline=a.get("inline", False),
+                    index=i,
+                )
+                for i, a in enumerate(data.get("attachments") or [])
+            ],
+            raw_size=data.get("raw_size", 0),
+            expires_at=_parse_dt(data["expires_at"]),
+        )
+
+
+@dataclass
+class InboxSummary:
+    id: str
+    local_part: str
+    fqdn: str
+    ttl_expires_at: Optional[datetime]
+    created_at: datetime
+    message_count: int
+
+    @property
+    def email_address(self) -> str:
+        return f"{self.local_part}@{self.fqdn}"
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "InboxSummary":
+        ttl = data.get("ttl_expires_at")
+        return cls(
+            id=data["id"],
+            local_part=data["local_part"],
+            fqdn=data["fqdn"],
+            ttl_expires_at=_parse_dt(ttl) if ttl else None,
+            created_at=_parse_dt(data["created_at"]),
+            message_count=data.get("message_count", 0),
+        )
+
+
+@dataclass
+class Domain:
+    id: str
+    fqdn: str
+    kind: str
+    verified_at: Optional[datetime]
+    mx_ok_at: Optional[datetime]
+    created_at: datetime
+    #: DNS records to publish while unverified: {"txt": {...}, "mx": {...}}.
+    setup: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Domain":
+        verified = data.get("verified_at")
+        mx_ok = data.get("mx_ok_at")
+        return cls(
+            id=data["id"],
+            fqdn=data["fqdn"],
+            kind=data["kind"],
+            verified_at=_parse_dt(verified) if verified else None,
+            mx_ok_at=_parse_dt(mx_ok) if mx_ok else None,
+            created_at=_parse_dt(data["created_at"]),
+            setup=data.get("setup"),
+        )
+
+
+@dataclass
+class DomainVerification:
+    id: str
+    fqdn: str
+    txt_ok: bool
+    mx_ok: bool
+    verified_at: Optional[datetime]
+    mx_ok_at: Optional[datetime]
+    setup: Dict[str, Any]
+
+    @property
+    def verified(self) -> bool:
+        return self.verified_at is not None and self.mx_ok_at is not None
+
+
+@dataclass
+class ApiKey:
+    id: str
+    prefix: str
+    label: Optional[str]
+    created_at: datetime
+    revoked_at: Optional[datetime]
+
+
+@dataclass
+class CreatedApiKey:
+    id: str
+    prefix: str
+    #: The raw key. Shown exactly once — store it now.
+    key: str
+
+
+@dataclass
+class Webhook:
+    """A registered webhook endpoint (paid plans)."""
+
+    id: str
+    url: str
+    description: Optional[str]
+    #: Masked signing secret, e.g. "whsec_…abcd".
+    secret_hint: str
+    consecutive_failures: int
+    disabled_at: Optional[datetime]
+    disabled_reason: Optional[str]
+    created_at: datetime
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Webhook":
+        disabled = data.get("disabled_at")
+        return cls(
+            id=data["id"],
+            url=data["url"],
+            description=data.get("description"),
+            secret_hint=data["secret_hint"],
+            consecutive_failures=data.get("consecutive_failures", 0),
+            disabled_at=_parse_dt(disabled) if disabled else None,
+            disabled_reason=data.get("disabled_reason"),
+            created_at=_parse_dt(data["created_at"]),
+        )
+
+
+@dataclass
+class CreatedWebhook:
+    id: str
+    url: str
+    description: Optional[str]
+    #: The signing secret. Shown exactly once — store it now.
+    secret: str
+    created_at: datetime
+
+
+@dataclass
+class WebhookDelivery:
+    """One event delivery attempt trail for an endpoint."""
+
+    id: str
+    event_type: str
+    #: pending | succeeded | failed | skipped
+    status: str
+    attempts: int
+    next_attempt_at: datetime
+    last_status_code: Optional[int]
+    last_error: Optional[str]
+    created_at: datetime
+    delivered_at: Optional[datetime]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "WebhookDelivery":
+        delivered = data.get("delivered_at")
+        return cls(
+            id=data["id"],
+            event_type=data["event_type"],
+            status=data["status"],
+            attempts=data["attempts"],
+            next_attempt_at=_parse_dt(data["next_attempt_at"]),
+            last_status_code=data.get("last_status_code"),
+            last_error=data.get("last_error"),
+            created_at=_parse_dt(data["created_at"]),
+            delivered_at=_parse_dt(delivered) if delivered else None,
+        )
+
+
+def verify_webhook_signature(
+    payload: bytes,
+    header: str,
+    secret: str,
+    tolerance: float = 300.0,
+    now: Optional[float] = None,
+) -> bool:
+    """Verify an ``X-MailFixture-Signature`` header against the raw request
+    body: ``t=<unix>,v1=<hex hmac-sha256(secret, "t.body")>``, Stripe-style.
+
+    ``tolerance`` bounds the timestamp age in seconds (replay protection);
+    ``now`` overrides the clock for tests. Constant-time comparison.
+    """
+    timestamp: Optional[int] = None
+    candidates: List[str] = []
+    for part in header.split(","):
+        name, _, value = part.strip().partition("=")
+        if name == "t" and value.isdigit():
+            timestamp = int(value)
+        elif name == "v1" and value:
+            candidates.append(value)
+    if timestamp is None or not candidates:
+        return False
+    clock = time.time() if now is None else now
+    if abs(clock - timestamp) > tolerance:
+        return False
+    mac = hmac.new(secret.encode(), f"{timestamp}.".encode() + payload, hashlib.sha256)
+    expected = mac.hexdigest()
+    return any(hmac.compare_digest(expected, candidate) for candidate in candidates)
+
+
+@dataclass
+class Inbox:
+    """A created inbox plus the wait helpers bound to it."""
+
+    id: str
+    email_address: str
+    local_part: str
+    domain: str
+    ttl_expires_at: Optional[datetime]
+    created_at: datetime
+    _client: "MailFixture" = field(repr=False, compare=False, default=None)  # type: ignore[assignment]
+
+    @property
+    def address(self) -> str:
+        """Alias for `email_address`."""
+        return self.email_address
+
+    def messages(
+        self,
+        since: Optional[str] = None,
+        match: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> List[MessageSummary]:
+        return self._client.list_messages(self.id, since=since, match=match, wait=wait)
+
+    def wait_for_message(
+        self, match: Optional[str] = None, timeout: float = 45.0
+    ) -> Message:
+        return self._client.wait_for_message(self.id, match=match, timeout=timeout)
+
+    def wait_for_otp(self, match: Optional[str] = None, timeout: float = 45.0) -> str:
+        return self._client.wait_for_otp(self.id, match=match, timeout=timeout)
+
+    def wait_for_link(
+        self,
+        kind: Optional[str] = None,
+        match: Optional[str] = None,
+        timeout: float = 45.0,
+    ) -> Link:
+        return self._client.wait_for_link(self.id, kind=kind, match=match, timeout=timeout)
+
+    def clear(self) -> None:
+        self._client.clear_inbox(self.id)
+
+    def delete(self) -> None:
+        self._client.delete_inbox(self.id)
+
+
+class MailFixture:
+    """Synchronous MailFixture API client.
+
+    Args:
+        api_key: `mfx_` API key; defaults to `MAILFIXTURE_API_KEY`
+            (or `MAILFIXTURE_KEY`) from the environment.
+        base_url: API origin; defaults to `MAILFIXTURE_BASE_URL` or
+            the hosted API.
+        timeout: socket timeout for plain (non-long-poll) requests.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = (
+            api_key
+            or os.environ.get("MAILFIXTURE_API_KEY")
+            or os.environ.get("MAILFIXTURE_KEY")
+        )
+        if not self.api_key:
+            raise MailFixtureError(
+                None,
+                "missing API key",
+                "pass api_key= or set MAILFIXTURE_API_KEY",
+            )
+        self.base_url = (
+            base_url or os.environ.get("MAILFIXTURE_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+
+    # -- inboxes -----------------------------------------------------------
+
+    def create_inbox(
+        self,
+        local_part: Optional[str] = None,
+        domain: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> Inbox:
+        """Create an inbox. With no arguments: a random address on the
+        shared domain, kept until you delete it."""
+        body: Dict[str, Any] = {}
+        if local_part is not None:
+            body["local_part"] = local_part
+        if domain is not None:
+            body["domain"] = domain
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        data = self._request("POST", "/v1/inboxes", body=body)
+        ttl = data.get("ttl_expires_at")
+        return Inbox(
+            id=data["id"],
+            email_address=data["email_address"],
+            local_part=data["local_part"],
+            domain=data["domain"],
+            ttl_expires_at=_parse_dt(ttl) if ttl else None,
+            created_at=_parse_dt(data["created_at"]),
+            _client=self,
+        )
+
+    def list_inboxes(self) -> List[InboxSummary]:
+        data = self._request("GET", "/v1/inboxes")
+        return [InboxSummary._from_json(i) for i in data["inboxes"]]
+
+    def delete_inbox(self, inbox_id: str) -> None:
+        self._request("DELETE", f"/v1/inboxes/{inbox_id}")
+
+    def clear_inbox(self, inbox_id: str) -> None:
+        """Drop an inbox's messages but keep the address."""
+        self._request("POST", f"/v1/inboxes/{inbox_id}/clear")
+
+    # -- messages ----------------------------------------------------------
+
+    def list_messages(
+        self,
+        inbox_id: str,
+        since: Optional[str] = None,
+        match: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> List[MessageSummary]:
+        """List an inbox's messages, oldest first.
+
+        `match` filters with `subject:`, `from:` or `to:` prefixes (a bare
+        term matches the subject). `wait` long-polls up to that many
+        seconds (server ceiling 60) until a matching message arrives.
+        """
+        params: Dict[str, str] = {}
+        if since is not None:
+            params["since"] = since
+        if match is not None:
+            params["match"] = match
+        if wait is not None:
+            params["wait"] = str(wait)
+        data = self._request(
+            "GET",
+            f"/v1/inboxes/{inbox_id}/messages",
+            params=params,
+            read_timeout=(wait or 0) + 15,
+        )
+        return [MessageSummary._from_json(m) for m in data["messages"]]
+
+    def get_message(self, message_id: str) -> Message:
+        return Message._from_json(self._request("GET", f"/v1/messages/{message_id}"))
+
+    def get_otp(self, message_id: str) -> Otp:
+        return Otp._from_json(self._request("GET", f"/v1/messages/{message_id}/otp"))
+
+    def get_links(self, message_id: str) -> List[Link]:
+        data = self._request("GET", f"/v1/messages/{message_id}/links")
+        return [Link._from_json(l) for l in data["links"]]
+
+    def download_attachment(self, message_id: str, index: int) -> bytes:
+        """Decoded bytes of one attachment (index into `Message.attachments`)."""
+        return self._request_raw("GET", f"/v1/messages/{message_id}/attachments/{index}")
+
+    # -- wait helpers (the point of the SDK) --------------------------------
+
+    def wait_for_message(
+        self,
+        inbox_id: str,
+        match: Optional[str] = None,
+        timeout: float = 45.0,
+        since: Optional[str] = None,
+    ) -> Message:
+        """Long-poll until a matching message arrives; returns the full
+        message. Raises `MailFixtureTimeout` after `timeout` seconds."""
+        deadline = time.monotonic() + timeout
+        cursor = since
+        while True:
+            remaining = deadline - time.monotonic()
+            summaries = self._poll(inbox_id, cursor, match, remaining)
+            if summaries:
+                return self.get_message(summaries[0].id)
+            if deadline - time.monotonic() <= 0:
+                raise MailFixtureTimeout(
+                    f"no message matching {match!r} within {timeout}s"
+                )
+
+    def wait_for_otp(
+        self, inbox_id: str, match: Optional[str] = None, timeout: float = 45.0
+    ) -> str:
+        """Long-poll until a message with an extracted OTP arrives and
+        return the best candidate. Messages without an OTP are skipped."""
+        for message_id in self._new_messages(inbox_id, match, timeout):
+            best = self.get_otp(message_id).best
+            if best:
+                return best
+        raise MailFixtureTimeout(f"no message with an OTP within {timeout}s")
+
+    def wait_for_link(
+        self,
+        inbox_id: str,
+        kind: Optional[str] = None,
+        match: Optional[str] = None,
+        timeout: float = 45.0,
+    ) -> Link:
+        """Long-poll until a message containing a link arrives and return
+        the first link — optionally only of `kind`
+        (verify | reset | unsubscribe | other)."""
+        for message_id in self._new_messages(inbox_id, match, timeout):
+            for link in self.get_links(message_id):
+                if kind is None or link.kind == kind:
+                    return link
+        raise MailFixtureTimeout(
+            f"no message with a {kind or 'any'} link within {timeout}s"
+        )
+
+    def _new_messages(self, inbox_id: str, match: Optional[str], timeout: float):
+        """Yield message ids as they arrive until the deadline passes."""
+        deadline = time.monotonic() + timeout
+        cursor: Optional[str] = None
+        while True:
+            remaining = deadline - time.monotonic()
+            summaries = self._poll(inbox_id, cursor, match, remaining)
+            for summary in summaries:
+                cursor = summary.received_at_raw
+                yield summary.id
+            if not summaries and deadline - time.monotonic() <= 0:
+                return
+
+    def _poll(
+        self,
+        inbox_id: str,
+        since: Optional[str],
+        match: Optional[str],
+        remaining: float,
+    ) -> List[MessageSummary]:
+        """One long-poll chunk, rate-limit aware."""
+        wait = max(0, min(math.ceil(remaining), MAX_SERVER_WAIT))
+        try:
+            return self.list_messages(inbox_id, since=since, match=match, wait=wait)
+        except MailFixtureError as err:
+            if err.status == 429 and err.retry_after and err.retry_after < remaining:
+                time.sleep(err.retry_after)
+                return []
+            raise
+
+    # -- domains -----------------------------------------------------------
+
+    def create_domain(self, fqdn: str) -> Domain:
+        """Register a custom domain; `Domain.setup` carries the TXT + MX
+        records to publish."""
+        return Domain._from_json(self._request("POST", "/v1/domains", body={"fqdn": fqdn}))
+
+    def list_domains(self) -> List[Domain]:
+        data = self._request("GET", "/v1/domains")
+        return [Domain._from_json(d) for d in data["domains"]]
+
+    def verify_domain(self, domain_id: str) -> DomainVerification:
+        data = self._request("POST", f"/v1/domains/{domain_id}/verify")
+        verified = data.get("verified_at")
+        mx_ok_at = data.get("mx_ok_at")
+        return DomainVerification(
+            id=data["id"],
+            fqdn=data["fqdn"],
+            txt_ok=data["txt_ok"],
+            mx_ok=data["mx_ok"],
+            verified_at=_parse_dt(verified) if verified else None,
+            mx_ok_at=_parse_dt(mx_ok_at) if mx_ok_at else None,
+            setup=data.get("setup") or {},
+        )
+
+    def delete_domain(self, domain_id: str) -> None:
+        self._request("DELETE", f"/v1/domains/{domain_id}")
+
+    # -- API keys ----------------------------------------------------------
+
+    def create_key(self, label: Optional[str] = None) -> CreatedApiKey:
+        body = {"label": label} if label else {}
+        data = self._request("POST", "/v1/keys", body=body)
+        return CreatedApiKey(id=data["id"], prefix=data["prefix"], key=data["key"])
+
+    def list_keys(self) -> List[ApiKey]:
+        data = self._request("GET", "/v1/keys")
+        return [
+            ApiKey(
+                id=k["id"],
+                prefix=k["prefix"],
+                label=k.get("label"),
+                created_at=_parse_dt(k["created_at"]),
+                revoked_at=_parse_dt(k["revoked_at"]) if k.get("revoked_at") else None,
+            )
+            for k in data["keys"]
+        ]
+
+    def revoke_key(self, key_id: str) -> None:
+        self._request("DELETE", f"/v1/keys/{key_id}")
+
+    # -- webhooks (paid plans) ----------------------------------------------
+
+    def create_webhook(self, url: str, description: Optional[str] = None) -> CreatedWebhook:
+        """Register an HTTPS endpoint for `message.received` and
+        `domain.verified` events. `CreatedWebhook.secret` is shown once."""
+        body: Dict[str, Any] = {"url": url}
+        if description:
+            body["description"] = description
+        data = self._request("POST", "/v1/webhooks", body=body)
+        return CreatedWebhook(
+            id=data["id"],
+            url=data["url"],
+            description=data.get("description"),
+            secret=data["secret"],
+            created_at=_parse_dt(data["created_at"]),
+        )
+
+    def list_webhooks(self) -> List[Webhook]:
+        data = self._request("GET", "/v1/webhooks")
+        return [Webhook._from_json(w) for w in data["webhooks"]]
+
+    def delete_webhook(self, webhook_id: str) -> None:
+        self._request("DELETE", f"/v1/webhooks/{webhook_id}")
+
+    def list_webhook_deliveries(self, webhook_id: str, limit: int = 50) -> List[WebhookDelivery]:
+        data = self._request(
+            "GET", f"/v1/webhooks/{webhook_id}/deliveries", params={"limit": str(limit)}
+        )
+        return [WebhookDelivery._from_json(d) for d in data["deliveries"]]
+
+    def test_webhook(self, webhook_id: str) -> str:
+        """Queue an `endpoint.test` event; returns the delivery id."""
+        data = self._request("POST", f"/v1/webhooks/{webhook_id}/test")
+        return data["delivery_id"]
+
+    def enable_webhook(self, webhook_id: str) -> None:
+        """Clear an auto-disabled endpoint so deliveries resume."""
+        self._request("POST", f"/v1/webhooks/{webhook_id}/enable")
+
+    # -- transport ---------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+        read_timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        raw = self._request_raw(
+            method, path, body=body, params=params, read_timeout=read_timeout
+        )
+        if not raw:
+            return {}
+        return json.loads(raw)
+
+    def _request_raw(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, str]] = None,
+        read_timeout: Optional[float] = None,
+    ) -> bytes:
+        url = self.base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self.api_key}")
+        req.add_header("User-Agent", f"mailfixture-python/{__version__}")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(
+                req, timeout=max(read_timeout or 0, self.timeout)
+            ) as res:
+                return res.read()
+        except urllib.error.HTTPError as err:
+            raise self._problem(err) from None
+        except urllib.error.URLError as err:
+            raise MailFixtureError(None, "connection error", str(err.reason)) from None
+
+    @staticmethod
+    def _problem(err: urllib.error.HTTPError) -> MailFixtureError:
+        title, detail = "error", None
+        try:
+            problem = json.loads(err.read())
+            title = problem.get("title", title)
+            detail = problem.get("detail")
+        except (ValueError, OSError):
+            pass
+        retry_after = None
+        header = err.headers.get("Retry-After") if err.headers else None
+        if header and header.isdigit():
+            retry_after = int(header)
+        return MailFixtureError(err.code, title, detail, retry_after)

mailfixture-0.1.0/tests/test_client.py

@@ -0,0 +1,297 @@
+"""Unit tests against a stub of the real /v1 wire protocol.
+
+The stub mirrors the shapes the axum handlers actually serialize
+(see api/src/{inboxes,messages,keys_api,domains}.rs); if the API
+changes shape, change the stub in the same commit.
+"""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from mailfixture import (
+    MailFixture,
+    MailFixtureError,
+    MailFixtureTimeout,
+    verify_webhook_signature,
+)
+
+INBOX_ID = "0d4cc81e-73aa-4efc-a5a2-3d9166a95a3c"
+MSG_ID = "cb26ac0e-2ec9-40b8-a5f0-9f3a55b5f2ff"
+WH_ID = "5b8f7de2-1c34-4e11-9a95-6a7f2f0f4c21"
+WH_DELIVERY_ID = "7c1a2b3c-4d5e-4f60-8a9b-0c1d2e3f4a5b"
+T0 = "2026-07-05T12:00:00.000001Z"
+T1 = "2026-07-05T12:00:05.000002Z"
+
+MESSAGE_SUMMARY = {
+    "id": MSG_ID,
+    "received_at": T1,
+    "from_addr": "noreply@acme.test",
+    "to_addrs": ["x7f3@acme.mxsink.sh"],
+    "subject": "Your Acme code is 482913",
+}
+
+MESSAGE_DETAIL = {
+    **MESSAGE_SUMMARY,
+    "inbox_id": INBOX_ID,
+    "text_body": "Your code is 482913",
+    "html_body": None,
+    "headers": {"message-id": "<1@acme.test>"},
+    "extracted": {
+        "otp": {"best": "482913", "candidates": [{"value": "482913", "score": 9.5}]},
+        "links": [
+            {"url": "https://acme.test/verify?t=abc", "text": "Verify", "class": "verify"}
+        ],
+    },
+    "attachments": [
+        {"filename": "report.pdf", "content_type": "application/pdf", "size": 123, "inline": False}
+    ],
+    "raw_size": 2048,
+    "expires_at": "2026-07-08T12:00:05Z",
+}
+
+
+class Stub(BaseHTTPRequestHandler):
+    # Per-server-instance state, reset by each test via make_server().
+    state = None
+
+    def log_message(self, *args):
+        pass
+
+    def _json(self, status, payload, headers=None):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _problem(self, status, title, detail, headers=None):
+        self._json(status, {"type": "about:blank", "title": title, "status": status, "detail": detail}, headers)
+
+    def do_POST(self):
+        path = urlparse(self.path).path
+        length = int(self.headers.get("Content-Length") or 0)
+        body = json.loads(self.rfile.read(length)) if length else {}
+        self.state["requests"].append(("POST", self.path, body))
+
+        if path == "/v1/inboxes":
+            self._json(201, {
+                "id": INBOX_ID,
+                "email_address": "x7f3@acme.mxsink.sh",
+                "local_part": "x7f3",
+                "domain": "acme.mxsink.sh",
+                "ttl_expires_at": None,
+                "created_at": T0,
+            })
+        elif path == f"/v1/inboxes/{INBOX_ID}/clear":
+            self.send_response(204)
+            self.end_headers()
+        elif path == "/v1/keys":
+            self._json(201, {"id": MSG_ID, "prefix": "mfx_ab12", "key": "mfx_ab12_secret"})
+        elif path == "/v1/webhooks":
+            self._json(201, {
+                "id": WH_ID, "url": body["url"], "description": body.get("description"),
+                "secret": "whsec_stubsecretstubsecretstubsecret1", "created_at": T0,
+            })
+        elif path == f"/v1/webhooks/{WH_ID}/test":
+            self._json(202, {"delivery_id": WH_DELIVERY_ID})
+        elif path == f"/v1/webhooks/{WH_ID}/enable":
+            self.send_response(204)
+            self.end_headers()
+        elif path == "/v1/domains":
+            self._json(201, {
+                "id": MSG_ID, "fqdn": body["fqdn"], "kind": "custom",
+                "verify_txt_token": "tok", "verified_at": None, "mx_ok_at": None,
+                "created_at": T0,
+                "setup": {"txt": {"name": "_mfx." + body["fqdn"], "value": "mfx-verify=tok"},
+                          "mx": {"name": body["fqdn"], "value": "mx.mailfixture.com", "priority": 10}},
+            })
+        else:
+            self._problem(404, "not found", "no such route")
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+        self.state["requests"].append(("GET", self.path, None))
+
+        if parsed.path == f"/v1/inboxes/{INBOX_ID}/messages":
+            polls = self.state["polls"]
+            self.state["polls"] += 1
+            deliver_on = self.state.get("deliver_on_poll", 0)
+            since = query.get("since", [None])[0]
+            if polls >= deliver_on and since != T1:
+                self._json(200, {"messages": [MESSAGE_SUMMARY]})
+            elif self.state.get("rate_limit_first") and polls == 0:
+                self._problem(429, "too many requests", "slow down", {"Retry-After": "1"})
+            else:
+                self._json(200, {"messages": []})
+        elif parsed.path == f"/v1/messages/{MSG_ID}":
+            self._json(200, MESSAGE_DETAIL)
+        elif parsed.path == f"/v1/messages/{MSG_ID}/otp":
+            self._json(200, MESSAGE_DETAIL["extracted"]["otp"])
+        elif parsed.path == f"/v1/messages/{MSG_ID}/links":
+            self._json(200, {"links": MESSAGE_DETAIL["extracted"]["links"]})
+        elif parsed.path == "/v1/webhooks":
+            self._json(200, {"webhooks": [{
+                "id": WH_ID, "url": "https://ci.acme.dev/hooks", "description": "ci",
+                "secret_hint": "whsec_…ret1", "consecutive_failures": 0,
+                "disabled_at": None, "disabled_reason": None, "created_at": T0,
+            }]})
+        elif parsed.path == f"/v1/webhooks/{WH_ID}/deliveries":
+            self._json(200, {"deliveries": [{
+                "id": WH_DELIVERY_ID, "event_type": "message.received",
+                "status": "succeeded", "attempts": 2, "next_attempt_at": T1,
+                "last_status_code": 200, "last_error": None,
+                "created_at": T0, "delivered_at": T1,
+            }]})
+        elif parsed.path == f"/v1/messages/{MSG_ID}/attachments/0":
+            self.send_response(200)
+            self.send_header("Content-Type", "application/octet-stream")
+            self.end_headers()
+            self.wfile.write(b"%PDF-fake")
+        else:
+            self._problem(404, "not found", "no such route")
+
+    def do_DELETE(self):
+        self.state["requests"].append(("DELETE", self.path, None))
+        self.send_response(204)
+        self.end_headers()
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        state = {"requests": [], "polls": 0}
+        handler = type("H", (Stub,), {"state": state})
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+        self.state = state
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.client = MailFixture(
+            api_key="mfx_test",
+            base_url=f"http://127.0.0.1:{self.server.server_address[1]}",
+        )
+
+    def tearDown(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+    def test_create_inbox_and_fields(self):
+        inbox = self.client.create_inbox(local_part="x7f3", ttl_seconds=900)
+        self.assertEqual(inbox.email_address, "x7f3@acme.mxsink.sh")
+        self.assertEqual(inbox.address, inbox.email_address)
+        method, path, body = self.state["requests"][0]
+        self.assertEqual(body, {"local_part": "x7f3", "ttl_seconds": 900})
+
+    def test_wait_for_otp_immediate(self):
+        inbox = self.client.create_inbox()
+        otp = inbox.wait_for_otp(timeout=5)
+        self.assertEqual(otp, "482913")
+
+    def test_wait_for_otp_after_empty_polls(self):
+        self.state["deliver_on_poll"] = 2
+        otp = self.client.wait_for_otp(INBOX_ID, timeout=10)
+        self.assertEqual(otp, "482913")
+        self.assertGreaterEqual(self.state["polls"], 3)
+
+    def test_wait_for_message_returns_full_detail(self):
+        message = self.client.wait_for_message(INBOX_ID, match="subject:Acme", timeout=5)
+        self.assertEqual(message.otp, "482913")
+        self.assertEqual(message.text_body, "Your code is 482913")
+        self.assertEqual(message.attachments[0].filename, "report.pdf")
+        poll_path = next(p for m, p, _ in self.state["requests"] if "/messages?" in p)
+        self.assertIn("match=subject%3AAcme", poll_path)
+        self.assertIn("wait=5", poll_path)
+
+    def test_wait_for_link_filters_kind(self):
+        link = self.client.wait_for_link(INBOX_ID, kind="verify", timeout=5)
+        self.assertEqual(link.url, "https://acme.test/verify?t=abc")
+        self.assertEqual(str(link), link.url)
+        with self.assertRaises(MailFixtureTimeout):
+            self.client.wait_for_link(INBOX_ID, kind="reset", timeout=0.2)
+
+    def test_timeout_raises(self):
+        self.state["deliver_on_poll"] = 10_000
+        with self.assertRaises(MailFixtureTimeout):
+            self.client.wait_for_message(INBOX_ID, timeout=0.2)
+
+    def test_rate_limit_retry_during_wait(self):
+        self.state["rate_limit_first"] = True
+        self.state["deliver_on_poll"] = 1
+        otp = self.client.wait_for_otp(INBOX_ID, timeout=10)
+        self.assertEqual(otp, "482913")
+
+    def test_problem_json_error(self):
+        with self.assertRaises(MailFixtureError) as ctx:
+            self.client.get_message("00000000-0000-0000-0000-000000000000")
+        self.assertEqual(ctx.exception.status, 404)
+        self.assertEqual(ctx.exception.title, "not found")
+
+    def test_attachment_download(self):
+        data = self.client.download_attachment(MSG_ID, 0)
+        self.assertEqual(data, b"%PDF-fake")
+
+    def test_keys_and_domains(self):
+        created = self.client.create_key(label="ci")
+        self.assertTrue(created.key.startswith("mfx_"))
+        domain = self.client.create_domain("tests.acme.dev")
+        self.assertEqual(domain.setup["mx"]["priority"], 10)
+        self.client.delete_domain(domain.id)
+        self.client.revoke_key(created.id)
+
+    def test_webhooks_crud_and_deliveries(self):
+        created = self.client.create_webhook("https://ci.acme.dev/hooks", description="ci")
+        self.assertTrue(created.secret.startswith("whsec_"))
+        method, path, body = self.state["requests"][0]
+        self.assertEqual(body, {"url": "https://ci.acme.dev/hooks", "description": "ci"})
+
+        hooks = self.client.list_webhooks()
+        self.assertEqual(hooks[0].secret_hint, "whsec_…ret1")
+        self.assertIsNone(hooks[0].disabled_at)
+
+        delivery_id = self.client.test_webhook(created.id)
+        self.assertEqual(delivery_id, WH_DELIVERY_ID)
+
+        deliveries = self.client.list_webhook_deliveries(created.id, limit=5)
+        self.assertEqual(deliveries[0].status, "succeeded")
+        self.assertEqual(deliveries[0].attempts, 2)
+        query = next(p for m, p, _ in self.state["requests"] if "/deliveries" in p)
+        self.assertIn("limit=5", query)
+
+        self.client.enable_webhook(created.id)
+        self.client.delete_webhook(created.id)
+        self.assertEqual(self.state["requests"][-1][0], "DELETE")
+
+    def test_verify_webhook_signature(self):
+        import hashlib
+        import hmac as hmac_mod
+
+        secret = "whsec_testsecret"
+        payload = b'{"id":"d-1","type":"endpoint.test"}'
+        t = 1_751_700_000
+        sig = hmac_mod.new(secret.encode(), f"{t}.".encode() + payload, hashlib.sha256).hexdigest()
+        header = f"t={t},v1={sig}"
+
+        self.assertTrue(verify_webhook_signature(payload, header, secret, now=t + 10))
+        # wrong secret / tampered body / stale timestamp / garbage header
+        self.assertFalse(verify_webhook_signature(payload, header, "whsec_other", now=t + 10))
+        self.assertFalse(verify_webhook_signature(b"{}", header, secret, now=t + 10))
+        self.assertFalse(verify_webhook_signature(payload, header, secret, now=t + 3600))
+        self.assertFalse(verify_webhook_signature(payload, "v1=deadbeef", secret, now=t))
+
+    def test_missing_api_key(self):
+        import os
+        old = {k: os.environ.pop(k, None) for k in ("MAILFIXTURE_API_KEY", "MAILFIXTURE_KEY")}
+        try:
+            with self.assertRaises(MailFixtureError):
+                MailFixture()
+        finally:
+            for k, v in old.items():
+                if v is not None:
+                    os.environ[k] = v
+
+
+if __name__ == "__main__":
+    unittest.main()