mailpier-inbox 0.1.0__tar.gz

mailpier_inbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solutions Group Unlimited
+
+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.

mailpier_inbox-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: mailpier-inbox
+Version: 0.1.0
+Summary: MailPier Inbox client for Python tests: a fresh email address per test, wait for the mail, read its code and links. Includes a pytest fixture.
+Author: Solutions Group Unlimited
+License-Expression: MIT
+Project-URL: Homepage, https://mailpier.io
+Project-URL: Documentation, https://mailpier.io/docs
+Keywords: email,testing,inbox,otp,pytest,e2e,mailpier
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# mailpier-inbox
+
+Python client for [MailPier Inbox](https://mailpier.io): give each test its own email address, wait for the mail your app
+sends, and read its one-time code and links. Python 3.9+, typed, one dependency (`requests`). Includes a **pytest fixture** and a
+**fake MailPier API** for offline tests.
+
+## Quick start
+
+```python
+from mailpier_inbox import MailPierInbox
+inbox = MailPierInbox()                                   # key from MAILPIER_API_KEY
+address = inbox.new_address(prefix="signup")              # signup-k3v9q2mz7a@qa.acme.mailpier.io
+sign_up(address)                                          # your app sends the mail
+mail = inbox.wait_for_message(address, subject_contains="Confirm", timeout=60)
+print(mail.code, mail.first_link("verify"))               # 482913 https://app.example.com/verify?t=...
+```
+
+Create the API key on your environment's **API keys** page and keep it in a secret (`MAILPIER_API_KEY`).
+
+## pytest
+
+Installing the package registers the plugin. The `mailpier_inbox` fixture returns the next mail to an address on each wait:
+
+```python
+def test_sign_up(mailpier_inbox, page):
+    email = mailpier_inbox.new_address()
+    page.fill("#email", email); page.click("text=Create account")
+    page.fill("#code", mailpier_inbox.wait_for_code(email))
+    # or: page.goto(mailpier_inbox.wait_for_link(email, "verify"))
+```
+
+`@pytest.mark.mailpier_cleanup` (or `pytest --mailpier-cleanup`) deletes the test's mail afterwards. Without `MAILPIER_API_KEY`
+the fixture fails with a clear message. For offline tests also request `mailpier_fake`: the fixture then talks to an in-memory fake
+API and you "send" mail with `mailpier_fake.deliver(email, subject=..., text=..., html=...)` (see `examples/`).
+
+## API
+
+| Call | What it does |
+|---|---|
+| `MailPierInbox(api_key=None, base_url=None, *, max_retries=5, max_retry_delay=60.0, session=None)` | Key from `MAILPIER_API_KEY`, root from `MAILPIER_BASE_URL` or `https://api.mailpier.io`. Context manager. |
+| `new_address(prefix=None, domain=None)` | A fresh random address of the key's environment. |
+| `wait_for_message(to, *, subject_contains=None, timeout=60, since=None, after_id=None)` | The **oldest** match received at or after `since`; long-polls; raises `MailPierTimeoutError` (a `TimeoutError`). |
+| `wait_for_next_message(previous, to, ...)` | The mail after `previous` (never `previous` again). |
+| `list_messages(to=None, *, subject_contains=None, since=None, take=50, skip=0)` | Newest first, at most 100 per call. |
+| `get_message(id)` / `get_raw(id)` / `get_attachment(id, index)` | Full mail / `.eml` bytes / attachment bytes; `None` when gone. |
+| `delete_message(id)` / `delete_all(to)` | Clean up. |
+| `message.code` / `message.first_link(contains=None)` | The first one-time code; the first link whose URL or text contains it. |
+
+Errors raise `MailPierInboxError` with `status` (0 = unreachable) and the server's message. 429 is retried after `Retry-After`,
+502/503/504 and connection errors with backoff, up to `max_retries` times.
+
+## Offline: the fake API
+
+```python
+from mailpier_inbox.testing import FakeMailPier
+with FakeMailPier() as fake:                              # 127.0.0.1, key "mpi_test_key", zone qa.demo.mailpier.io
+    inbox = MailPierInbox(api_key=fake.api_key, base_url=fake.url)
+    fake.deliver(address, subject="Confirm", text="Your code is 482913")
+```
+
+## Develop
+
+`python -m venv .venv`, `.venv\Scripts\pip install -e .[test]`, `.venv\Scripts\python -m pytest`; runnable example:
+`python examples/quickstart.py`. `..\test-all.ps1` runs everything. License: MIT.

mailpier_inbox-0.1.0/README.md

@@ -0,0 +1,64 @@
+# mailpier-inbox
+
+Python client for [MailPier Inbox](https://mailpier.io): give each test its own email address, wait for the mail your app
+sends, and read its one-time code and links. Python 3.9+, typed, one dependency (`requests`). Includes a **pytest fixture** and a
+**fake MailPier API** for offline tests.
+
+## Quick start
+
+```python
+from mailpier_inbox import MailPierInbox
+inbox = MailPierInbox()                                   # key from MAILPIER_API_KEY
+address = inbox.new_address(prefix="signup")              # signup-k3v9q2mz7a@qa.acme.mailpier.io
+sign_up(address)                                          # your app sends the mail
+mail = inbox.wait_for_message(address, subject_contains="Confirm", timeout=60)
+print(mail.code, mail.first_link("verify"))               # 482913 https://app.example.com/verify?t=...
+```
+
+Create the API key on your environment's **API keys** page and keep it in a secret (`MAILPIER_API_KEY`).
+
+## pytest
+
+Installing the package registers the plugin. The `mailpier_inbox` fixture returns the next mail to an address on each wait:
+
+```python
+def test_sign_up(mailpier_inbox, page):
+    email = mailpier_inbox.new_address()
+    page.fill("#email", email); page.click("text=Create account")
+    page.fill("#code", mailpier_inbox.wait_for_code(email))
+    # or: page.goto(mailpier_inbox.wait_for_link(email, "verify"))
+```
+
+`@pytest.mark.mailpier_cleanup` (or `pytest --mailpier-cleanup`) deletes the test's mail afterwards. Without `MAILPIER_API_KEY`
+the fixture fails with a clear message. For offline tests also request `mailpier_fake`: the fixture then talks to an in-memory fake
+API and you "send" mail with `mailpier_fake.deliver(email, subject=..., text=..., html=...)` (see `examples/`).
+
+## API
+
+| Call | What it does |
+|---|---|
+| `MailPierInbox(api_key=None, base_url=None, *, max_retries=5, max_retry_delay=60.0, session=None)` | Key from `MAILPIER_API_KEY`, root from `MAILPIER_BASE_URL` or `https://api.mailpier.io`. Context manager. |
+| `new_address(prefix=None, domain=None)` | A fresh random address of the key's environment. |
+| `wait_for_message(to, *, subject_contains=None, timeout=60, since=None, after_id=None)` | The **oldest** match received at or after `since`; long-polls; raises `MailPierTimeoutError` (a `TimeoutError`). |
+| `wait_for_next_message(previous, to, ...)` | The mail after `previous` (never `previous` again). |
+| `list_messages(to=None, *, subject_contains=None, since=None, take=50, skip=0)` | Newest first, at most 100 per call. |
+| `get_message(id)` / `get_raw(id)` / `get_attachment(id, index)` | Full mail / `.eml` bytes / attachment bytes; `None` when gone. |
+| `delete_message(id)` / `delete_all(to)` | Clean up. |
+| `message.code` / `message.first_link(contains=None)` | The first one-time code; the first link whose URL or text contains it. |
+
+Errors raise `MailPierInboxError` with `status` (0 = unreachable) and the server's message. 429 is retried after `Retry-After`,
+502/503/504 and connection errors with backoff, up to `max_retries` times.
+
+## Offline: the fake API
+
+```python
+from mailpier_inbox.testing import FakeMailPier
+with FakeMailPier() as fake:                              # 127.0.0.1, key "mpi_test_key", zone qa.demo.mailpier.io
+    inbox = MailPierInbox(api_key=fake.api_key, base_url=fake.url)
+    fake.deliver(address, subject="Confirm", text="Your code is 482913")
+```
+
+## Develop
+
+`python -m venv .venv`, `.venv\Scripts\pip install -e .[test]`, `.venv\Scripts\python -m pytest`; runnable example:
+`python examples/quickstart.py`. `..\test-all.ps1` runs everything. License: MIT.

mailpier_inbox-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mailpier-inbox"
+version = "0.1.0"
+description = "MailPier Inbox client for Python tests: a fresh email address per test, wait for the mail, read its code and links. Includes a pytest fixture."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Solutions Group Unlimited" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28"]
+keywords = ["email", "testing", "inbox", "otp", "pytest", "e2e", "mailpier"]
+classifiers = [
+  "Framework :: Pytest",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://mailpier.io"
+Documentation = "https://mailpier.io/docs"
+
+[project.entry-points.pytest11]
+mailpier_inbox = "mailpier_inbox.pytest_plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mailpier_inbox = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "examples"]
+python_files = ["test_*.py"]

mailpier_inbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mailpier_inbox-0.1.0/src/mailpier_inbox/__init__.py

@@ -0,0 +1,12 @@
+"""MailPier Inbox client: a fresh email address per test, wait for the mail, read its code and links."""
+
+from .client import DEFAULT_BASE_URL, MAX_POLL_SECONDS, VERSION, MailPierInbox
+from .errors import MailPierInboxError, MailPierTimeoutError
+from .message import InboxAttachment, InboxLink, InboxMessage, InboxMessageSummary
+from .session import InboxSession
+
+__version__ = VERSION
+__all__ = [
+    "DEFAULT_BASE_URL", "MAX_POLL_SECONDS", "MailPierInbox", "MailPierInboxError", "MailPierTimeoutError",
+    "InboxMessage", "InboxMessageSummary", "InboxLink", "InboxAttachment", "InboxSession", "__version__",
+]

mailpier_inbox-0.1.0/src/mailpier_inbox/client.py

@@ -0,0 +1,217 @@
+"""Client for the MailPier Inbox API (https://api.mailpier.io/v1)."""
+
+from __future__ import annotations
+
+import email.utils
+import math
+import os
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+from .errors import MailPierInboxError, MailPierTimeoutError
+from .message import InboxMessage, InboxMessageSummary
+
+DEFAULT_BASE_URL = "https://api.mailpier.io"
+MAX_POLL_SECONDS = 120
+"""The server caps one long-poll at 120 seconds; longer waits are made of several polls."""
+VERSION = "0.1.0"
+
+Since = Union[datetime, str, None]
+
+
+def _iso(t: Since) -> Optional[str]:
+    if t is None:
+        return None
+    if isinstance(t, str):
+        return t
+    if t.tzinfo is None:
+        t = t.replace(tzinfo=timezone.utc)
+    return t.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class MailPierInbox:
+    """Client for MailPier Inbox. Create one per API key and reuse it (thread-safe for separate calls).
+
+    >>> inbox = MailPierInbox()                      # key from MAILPIER_API_KEY
+    >>> address = inbox.new_address(prefix="signup")
+    >>> # ... make your app send a mail to address ...
+    >>> mail = inbox.wait_for_message(address, subject_contains="Confirm", timeout=60)
+    >>> mail.code, mail.first_link("verify")
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, *, max_retries: int = 5,
+                 max_retry_delay: float = 60.0, session: Optional[requests.Session] = None) -> None:
+        """
+        :param api_key: An API key from the environment's API keys page (``mpi_...``); default MAILPIER_API_KEY.
+        :param base_url: API root; default MAILPIER_BASE_URL or https://api.mailpier.io.
+        :param max_retries: How often one call is retried on 429 (after Retry-After), 502/503/504 and connection errors.
+        :param max_retry_delay: The longest single pause between retries, in seconds (Retry-After is honoured up to this).
+        """
+        key = (api_key or os.environ.get("MAILPIER_API_KEY") or "").strip()
+        if not key:
+            raise ValueError("An API key (mpi_...) is required: pass api_key or set MAILPIER_API_KEY.")
+        self._key = key
+        self.base_url = (base_url or os.environ.get("MAILPIER_BASE_URL") or DEFAULT_BASE_URL).strip().rstrip("/")
+        self.max_retries = max(0, max_retries)
+        self.max_retry_delay = max(0.0, max_retry_delay)
+        self._session = session or requests.Session()
+        self._owns_session = session is None
+
+    def __enter__(self) -> "MailPierInbox":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_session:
+            self._session.close()
+
+    def __repr__(self) -> str:   # never show the key
+        return f"MailPierInbox(base_url={self.base_url!r})"
+
+    # ------------------------------------------------------------------ API
+
+    def new_address(self, prefix: Optional[str] = None, domain: Optional[str] = None) -> str:
+        """A fresh random address of the key's environment, e.g. ``signup-k3v9q2mz7a@qa.acme.mailpier.io``."""
+        body = {k: v for k, v in (("prefix", prefix), ("domain", domain)) if v}
+        r = self._request("POST", "/v1/addresses", json=body)
+        address = (r.json() or {}).get("address")
+        if not address:
+            raise MailPierInboxError(r.status_code, "The server returned no address.")
+        return address
+
+    def wait_for_message(self, to: str, *, subject_contains: Optional[str] = None, timeout: float = 60.0,
+                         since: Since = None, after_id: Optional[str] = None) -> InboxMessage:
+        """Waits until a mail to ``to`` arrives and returns it (the OLDEST match received at or after ``since``).
+
+        :param timeout: seconds to wait in total.
+        :param since: only mail received at or after this time (pass the time your test started).
+        :param after_id: with ``since``: skip this mail (see wait_for_next_message).
+        :raises MailPierTimeoutError: when nothing arrives in time.
+        """
+        to = (to or "").strip()
+        if not to:
+            raise ValueError("wait_for_message needs the address (to).")
+        if not timeout or timeout <= 0:
+            raise ValueError("timeout must be greater than 0.")
+        deadline = time.monotonic() + timeout
+        since_text = _iso(since)
+        while True:
+            left = deadline - time.monotonic()
+            seconds = min(max(math.ceil(left), 1), MAX_POLL_SECONDS)
+            r = self._request("GET", "/v1/messages/wait", params={
+                "to": to, "subject": subject_contains, "since": since_text,
+                "afterId": after_id if since_text else None, "timeoutSeconds": seconds,
+            }, timeout=seconds + 30)
+            if r.status_code != 204:
+                return InboxMessage.from_json(r.json())
+            if time.monotonic() >= deadline:
+                raise MailPierTimeoutError(to, timeout, subject_contains)
+
+    def wait_for_next_message(self, previous: InboxMessageSummary, to: str, *, subject_contains: Optional[str] = None,
+                              timeout: float = 60.0) -> InboxMessage:
+        """The next mail to ``to`` after ``previous`` (one you already received); never ``previous`` itself."""
+        return self.wait_for_message(to, subject_contains=subject_contains, timeout=timeout,
+                                     since=previous.received_utc, after_id=previous.id)
+
+    def list_messages(self, to: Optional[str] = None, *, subject_contains: Optional[str] = None, since: Since = None,
+                      after_id: Optional[str] = None, take: int = 50, skip: int = 0) -> List[InboxMessageSummary]:
+        """Mail of the environment, newest first (at most 100 per call)."""
+        since_text = _iso(since)
+        r = self._request("GET", "/v1/messages", params={
+            "to": to, "subject": subject_contains, "since": since_text, "afterId": after_id if since_text else None,
+            "take": take, "skip": skip,
+        })
+        return [InboxMessageSummary.from_json(i) for i in (r.json() or {}).get("items") or []]
+
+    def get_message(self, message_id: str) -> Optional[InboxMessage]:
+        """One mail with text, HTML, headers, links, codes and attachments; None when it does not exist (or expired)."""
+        r = self._request("GET", f"/v1/messages/{message_id}", allow_404=True)
+        return None if r.status_code == 404 else InboxMessage.from_json(r.json())
+
+    def get_raw(self, message_id: str) -> Optional[bytes]:
+        """The original message (.eml bytes); None when it does not exist."""
+        r = self._request("GET", f"/v1/messages/{message_id}/raw", allow_404=True, accept="*/*")
+        return None if r.status_code == 404 else r.content
+
+    def get_attachment(self, message_id: str, index: int) -> Optional[bytes]:
+        """One attachment's bytes; None when it does not exist."""
+        r = self._request("GET", f"/v1/messages/{message_id}/attachments/{int(index)}", allow_404=True, accept="*/*")
+        return None if r.status_code == 404 else r.content
+
+    def delete_message(self, message_id: str) -> bool:
+        """Deletes one mail. False when it did not exist. Raises (409) when it was also sent outside this environment."""
+        return self._request("DELETE", f"/v1/messages/{message_id}", allow_404=True).status_code != 404
+
+    def delete_all(self, to: str) -> int:
+        """Deletes every mail to one address; returns how many were deleted."""
+        if not (to or "").strip():
+            raise ValueError("delete_all needs the address.")
+        return int((self._request("DELETE", "/v1/messages", params={"to": to.strip()}).json() or {}).get("deleted") or 0)
+
+    def me(self) -> Dict[str, Any]:
+        """The key's account, environment, domains, plan and usage."""
+        return self._request("GET", "/v1/me").json()
+
+    # ------------------------------------------------------------------ plumbing
+
+    def _request(self, method: str, path: str, *, params: Optional[Dict[str, Any]] = None, json: Any = None,
+                 timeout: float = 60.0, allow_404: bool = False, accept: str = "application/json") -> requests.Response:
+        """One call with retries: 429 waits Retry-After (default 1 s), 502/503/504 and connection errors back off
+        0.5, 1, 2, 4 ... s (both capped at max_retry_delay). Other errors raise MailPierInboxError with the server's text."""
+        url = self.base_url + path
+        clean = {k: v for k, v in (params or {}).items() if v is not None and v != ""}
+        headers = {"Authorization": f"Bearer {self._key}", "Accept": accept, "User-Agent": f"mailpier-inbox-python/{VERSION}"}
+        attempt = 0
+        while True:
+            try:
+                r = self._session.request(method, url, params=clean, json=json, headers=headers, timeout=(10, timeout))
+            except (requests.ConnectionError, requests.Timeout) as ex:
+                if attempt >= self.max_retries:
+                    raise MailPierInboxError(0, f"Could not reach MailPier Inbox at {self.base_url}: {ex}") from ex
+                time.sleep(self._backoff(attempt))
+                attempt += 1
+                continue
+            if r.ok or (allow_404 and r.status_code == 404):
+                return r
+            message = _error_text(r)
+            if r.status_code == 429:
+                retry_after = _retry_after(r.headers.get("Retry-After"))
+                if attempt < self.max_retries:
+                    time.sleep(min(retry_after if retry_after is not None else 1, self.max_retry_delay))
+                    attempt += 1
+                    continue
+                raise MailPierInboxError(429, message or "Too many requests.", retry_after)
+            if r.status_code in (502, 503, 504) and attempt < self.max_retries:
+                time.sleep(self._backoff(attempt))
+                attempt += 1
+                continue
+            raise MailPierInboxError(r.status_code, message or f"MailPier Inbox answered {r.status_code}.")
+
+    def _backoff(self, attempt: int) -> float:
+        return min(0.5 * (2 ** attempt), self.max_retry_delay)
+
+
+def _error_text(r: requests.Response) -> Optional[str]:
+    try:
+        e = r.json().get("error")
+        return f"{e} (HTTP {r.status_code})" if isinstance(e, str) and e else None
+    except (ValueError, AttributeError):
+        return None
+
+
+def _retry_after(v: Optional[str]) -> Optional[int]:
+    if not v:
+        return None
+    try:
+        return max(0, int(v))
+    except ValueError:
+        try:
+            when = email.utils.parsedate_to_datetime(v)
+            return max(0, math.ceil((when - datetime.now(timezone.utc)).total_seconds()))
+        except (TypeError, ValueError):
+            return None

mailpier_inbox-0.1.0/src/mailpier_inbox/errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class MailPierInboxError(Exception):
+    """The API answered an error: 400 (bad address/prefix), 401 (bad key), 403 (account suspended), 404, 409, 429, 503.
+
+    ``status`` is 0 when the server could not be reached at all.
+    """
+
+    def __init__(self, status: int, message: str, retry_after: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.retry_after = retry_after
+        """Set on 429: seconds to wait before the next call."""
+
+
+class MailPierTimeoutError(TimeoutError):
+    """No matching mail arrived before the timeout."""
+
+    def __init__(self, address: str, timeout: float, subject_contains: Optional[str] = None) -> None:
+        subject = f' with "{subject_contains}" in the subject' if subject_contains else ""
+        super().__init__(f"No mail to {address}{subject} arrived within {timeout:g} seconds.")
+        self.address = address
+        self.timeout = timeout

mailpier_inbox-0.1.0/src/mailpier_inbox/message.py

@@ -0,0 +1,111 @@
+"""The JSON shapes of the MailPier Inbox API (camelCase on the wire, snake_case here), mirroring the .NET client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class InboxLink:
+    href: str
+    text: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class InboxAttachment:
+    index: int
+    file_name: Optional[str] = None
+    content_type: Optional[str] = None
+    size: int = 0
+
+
+@dataclass(frozen=True)
+class InboxMessageSummary:
+    """A mail as the list call returns it. ``to`` holds the environment's own (envelope) recipients."""
+
+    id: str
+    received_utc: str
+    """ISO 8601, UTC."""
+    to: List[str] = field(default_factory=list)
+    from_: Optional[str] = None
+    subject: Optional[str] = None
+    size_bytes: int = 0
+    has_attachments: bool = False
+    """Exact up to 16 KiB, a best guess above; get_message is exact."""
+
+    @classmethod
+    def from_json(cls, d: Dict[str, Any]) -> "InboxMessageSummary":
+        return cls(**_summary_fields(d))
+
+
+@dataclass(frozen=True)
+class InboxMessage(InboxMessageSummary):
+    """A full mail with helpers: ``message.code`` and ``message.first_link("verify")``.
+
+    ``html`` is the HTML part as received, NOT sanitised: never render it in a page of your own origin.
+    """
+
+    text: Optional[str] = None
+    html: Optional[str] = None
+    headers: Optional[Dict[str, Any]] = None
+    links: List[InboxLink] = field(default_factory=list)
+    codes: List[str] = field(default_factory=list)
+    """One-time codes found in the mail (verification codes, OTPs, PINs), best guess first."""
+    attachments: List[InboxAttachment] = field(default_factory=list)
+    auth: Any = None
+    spam: Any = None
+    raw_json: Dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+    """The JSON exactly as the API returned it."""
+
+    @property
+    def code(self) -> Optional[str]:
+        """The first one-time code, or None when the mail has none."""
+        return self.codes[0] if self.codes else None
+
+    def first_link(self, contains: Optional[str] = None) -> Optional[str]:
+        """The first link whose address (or text) contains ``contains`` (case-insensitive); the first link when omitted."""
+        if not contains:
+            return self.links[0].href if self.links else None
+        needle = contains.lower()
+        for link in self.links:
+            if needle in link.href.lower() or needle in (link.text or "").lower():
+                return link.href
+        return None
+
+    @classmethod
+    def from_json(cls, d: Dict[str, Any]) -> "InboxMessage":
+        links = [InboxLink(href=l["href"], text=l.get("text")) for l in (d.get("links") or [])
+                 if isinstance(l, dict) and isinstance(l.get("href"), str)]
+        attachments = [InboxAttachment(index=int(a.get("index", i)), file_name=a.get("fileName"),
+                                       content_type=a.get("contentType"), size=int(a.get("size") or 0))
+                       for i, a in enumerate(d.get("attachments") or []) if isinstance(a, dict)]
+        return cls(**_summary_fields(d), text=d.get("text"), html=d.get("html"), headers=d.get("headers"), links=links,
+                   codes=_codes(d.get("codes")), attachments=attachments, auth=d.get("auth"), spam=d.get("spam"), raw_json=d)
+
+
+def _summary_fields(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "id": str(d.get("id", "")),
+        "received_utc": str(d.get("receivedUtc", "")),
+        "to": list(d.get("to") or []),
+        "from_": d.get("from"),
+        "subject": d.get("subject"),
+        "size_bytes": int(d.get("sizeBytes") or 0),
+        "has_attachments": bool(d.get("hasAttachments")),
+    }
+
+
+def _codes(value: Any) -> List[str]:
+    """Codes are strings; a richer shape (objects with value/code) is accepted like the .NET client does."""
+    out: List[str] = []
+    for c in value or []:
+        if isinstance(c, str) and c:
+            out.append(c)
+        elif isinstance(c, dict):
+            for k in ("value", "code", "Value", "Code"):
+                v = c.get(k)
+                if isinstance(v, str) and v:
+                    out.append(v)
+                    break
+    return out

mailpier_inbox-0.1.0/src/mailpier_inbox/pytest_plugin.py

@@ -0,0 +1,56 @@
+"""pytest plugin (registered automatically when mailpier-inbox is installed).
+
+Fixtures:
+- ``mailpier_inbox``: an InboxSession for one test (new_address, wait_for_message, wait_for_code, wait_for_link, plus every
+  client call). Key from MAILPIER_API_KEY, API root from MAILPIER_BASE_URL (default https://api.mailpier.io).
+  Mark a test ``@pytest.mark.mailpier_cleanup`` (or pass ``--mailpier-cleanup``) to delete its mail afterwards.
+- ``mailpier_fake``: a FAKE MailPier API on 127.0.0.1 for offline tests; ``mailpier_inbox`` uses it automatically
+  when the test also requests ``mailpier_fake``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+import pytest
+
+from .client import MailPierInbox
+from .session import InboxSession
+from .testing import FakeMailPier
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    parser.addoption("--mailpier-cleanup", action="store_true", default=False,
+                     help="MailPier Inbox: delete the mail of every address a test created when it ends.")
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line("markers", "mailpier_cleanup: delete this test's MailPier Inbox mail when it ends.")
+
+
+@pytest.fixture
+def mailpier_fake() -> Iterator[FakeMailPier]:
+    """A fake MailPier Inbox API (in memory, 127.0.0.1). Send mail with ``mailpier_fake.deliver(to=..., subject=..., text=...)``."""
+    with FakeMailPier() as fake:
+        yield fake
+
+
+@pytest.fixture
+def mailpier_inbox(request: pytest.FixtureRequest) -> Iterator[InboxSession]:
+    """An InboxSession for this test (see the module docstring)."""
+    if "mailpier_fake" in request.fixturenames:
+        fake: FakeMailPier = request.getfixturevalue("mailpier_fake")
+        client = MailPierInbox(api_key=fake.api_key, base_url=fake.url, max_retry_delay=0.05)
+    else:
+        if not (os.environ.get("MAILPIER_API_KEY") or "").strip():
+            pytest.fail("mailpier_inbox needs an API key: set MAILPIER_API_KEY (from your environment's API keys page).",
+                        pytrace=False)
+        client = MailPierInbox()
+    session = InboxSession(client)
+    try:
+        yield session
+    finally:
+        if request.config.getoption("--mailpier-cleanup") or request.node.get_closest_marker("mailpier_cleanup"):
+            session.cleanup()
+        client.close()