mailflat 0.3.3__tar.gz → 0.4.1__tar.gz

{mailflat-0.3.3 → mailflat-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailflat
-Version: 0.3.3
+Version: 0.4.1
 Summary: Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval.
 Project-URL: Homepage, https://mailflat.net
 Project-URL: Documentation, https://mailflat.net
@@ -14,10 +14,16 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Requires-Dist: httpx<1,>=0.24
 Provides-Extra: dev
 Requires-Dist: langchain-core>=0.2; extra == 'dev'
@@ -85,20 +91,42 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 ### `Inbox`
 - `.address` — the email address.
-- `.messages() -> list[Message]` — all messages, newest first.
-- `.latest() -> Message | None` — most recent message.
+- `.messages(*, direction="in") -> list[Message]` — messages, newest first.
+- `.latest(*, direction="in") -> Message | None` — most recent message.
 - `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
-- `.wait_for_message(*, timeout=30, poll_interval=1.0) -> Message` — poll until any message arrives.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
 - `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
+- `.burn() -> dict` — delete every message but keep the address.
+- `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
 - `.delete() -> dict` — delete the inbox and all its messages.
 
+> **Reads return received mail by default.** `direction="out"` returns mail you sent from
+> this address, `"all"` returns both. This matters for agent-to-agent flows: without it,
+> `send()` followed by `wait_for_message()` returns your own outgoing message.
+
 ### `Message`
-`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+
+- `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
+- `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
+  alone — send one from a normal mail client to test this path.
+- `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
+  (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
+  mailflat.net, so today this is `None` for every message.
+- `.headers` — raw headers, exactly as they arrived. Names are case-insensitive per
+  RFC 5322 but this is a plain dict, so **do not index it**: the real key is `Message-ID`,
+  and `headers["Message-Id"]` raises `KeyError`. Use `.header("message-id")` or `.message_id`.
+- `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors
 
-All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
-`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,
+still exported as `PermissionError` for compatibility — the new name no longer shadows the built-in),
+`NotFoundError` (404), `RateLimitError` (429, carries `.retry_after` when the server sent one),
+`APIError` (other), `OTPTimeoutError`
 (no OTP before timeout), `EncryptedInboxError` (the inbox is end-to-end encrypted, so the
 server cannot read its contents — use a non-encrypted inbox for agent automation).
 

{mailflat-0.3.3 → mailflat-0.4.1}/README.md

@@ -56,20 +56,42 @@ for self-hosted / BYOD deployments. Supports use as a context manager (`with Mai
 
 ### `Inbox`
 - `.address` — the email address.
-- `.messages() -> list[Message]` — all messages, newest first.
-- `.latest() -> Message | None` — most recent message.
+- `.messages(*, direction="in") -> list[Message]` — messages, newest first.
+- `.latest(*, direction="in") -> Message | None` — most recent message.
 - `.wait_for_otp(*, timeout=30, poll_interval=1.0) -> str` — poll until an OTP arrives; returns the code.
-- `.wait_for_message(*, timeout=30, poll_interval=1.0) -> Message` — poll until any message arrives.
+- `.wait_for_message(*, timeout=30, poll_interval=1.0, direction="in") -> Message` — poll until a message arrives.
 - `.send(to, *, subject="", body="", html=None) -> dict` — send a DKIM-signed email from this inbox.
+- `.mark_read(message_id) -> dict` — mark a message read so later polls can skip it.
+- `.burn() -> dict` — delete every message but keep the address.
+- `.download_attachment(message_id, attachment_id) -> bytes` — fetch an attachment's bytes.
 - `.delete() -> dict` — delete the inbox and all its messages.
 
+> **Reads return received mail by default.** `direction="out"` returns mail you sent from
+> this address, `"all"` returns both. This matters for agent-to-agent flows: without it,
+> `send()` followed by `wait_for_message()` returns your own outgoing message.
+
 ### `Message`
-`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`, `.raw`.
+`.otp`, `.subject`, `.sender`, `.text`, `.html`, `.to_address`, `.direction`, `.received_at`,
+`.links`, `.attachments`, `.spam`, `.headers`, `.is_read`, `.raw`.
+
+- `.links` — URLs found in the body (HTML hrefs first). For "click the verification link" flows.
+- `.attachments` — metadata; `msg.attachments[0].download()` fetches the bytes.
+  ⚠️ `send()` cannot attach files yet, so you cannot produce an attachment from the SDK
+  alone — send one from a normal mail client to test this path.
+- `.spam` — `{score, required, is_spam, rules, scanner}`, or `None` when never scanned
+  (which is not the same as a score of 0). ⚠️ Spam scanning is currently **disabled** on
+  mailflat.net, so today this is `None` for every message.
+- `.headers` — raw headers, exactly as they arrived. Names are case-insensitive per
+  RFC 5322 but this is a plain dict, so **do not index it**: the real key is `Message-ID`,
+  and `headers["Message-Id"]` raises `KeyError`. Use `.header("message-id")` or `.message_id`.
+- `.mark_read()` / `.delete()` — act on this message directly.
 
 ## Errors
 
-All errors subclass `MailFlatError`: `AuthenticationError` (401), `PermissionError` (403),
-`NotFoundError` (404), `RateLimitError` (429), `APIError` (other), `OTPTimeoutError`
+All errors subclass `MailFlatError`: `AuthenticationError` (401), `MailFlatPermissionError` (403,
+still exported as `PermissionError` for compatibility — the new name no longer shadows the built-in),
+`NotFoundError` (404), `RateLimitError` (429, carries `.retry_after` when the server sent one),
+`APIError` (other), `OTPTimeoutError`
 (no OTP before timeout), `EncryptedInboxError` (the inbox is end-to-end encrypted, so the
 server cannot read its contents — use a non-encrypted inbox for agent automation).
 

{mailflat-0.3.3 → mailflat-0.4.1}/pyproject.toml

@@ -10,7 +10,7 @@ name = "mailflat"
 dynamic = ["version"]
 description = "Official Python SDK for MailFlat — disposable, automation-friendly email inboxes with one-line OTP retrieval."
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [{ name = "MailFlat", email = "support@mailflat.net" }]
 keywords = ["email", "disposable-email", "otp", "automation", "testing", "ai-agents", "temporary-email"]
@@ -20,6 +20,16 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    # Aralığın İKİ UCU gerçekten koşuldu (3.11 + 3.14, 53 test yeşil). Aradaki sürümler için
+    # ayrı bir iddia yok: sürüme özgü API kullanmıyoruz ve `from __future__ import annotations`
+    # her dosyada var. Alt sınır 3.8 → 3.9: 3.8 EOL ve HİÇ test edilmedi; test edilmemiş bir
+    # sürümü desteklediğini söylemek, PyPI'da kullanıcıyı yanlış filtrelemeye götürür.
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Communications :: Email",
     "Topic :: Software Development :: Testing",
     "Typing :: Typed",

mailflat-0.4.1/src/mailflat/__init__.py

@@ -0,0 +1,59 @@
+"""MailFlat Python SDK — the official client for automation-friendly email inboxes.
+
+`pip install mailflat` → `from mailflat import MailFlat`.
+
+Connected to:
+  - imports from: mailflat.client, mailflat.inbox, mailflat.errors
+  - imported by:  user code, mailflat-mcp, mailflat.langchain
+
+Key exports:
+  - `MailFlat` — client
+  - `Inbox`, `Message`, `Attachment` — domain types
+  - errors: `MailFlatError`, `AuthenticationError`, `MailFlatPermissionError`,
+    `NotFoundError`, `RateLimitError`, `APIError`, `OTPTimeoutError`, `EncryptedInboxError`
+  - `redact_secrets()` — strips secret fields from agent tool output (used by MCP/LangChain)
+"""
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satır bilerek YORUM: docstring'e Türkçe not koymak, tam da kaçındığımız şeydi —
+# `help()` docstring'i basar, yorumu basmaz.
+from __future__ import annotations
+
+from .client import MailFlat
+from .errors import (
+    APIError,
+    AuthenticationError,
+    EncryptedInboxError,
+    MailFlatError,
+    MailFlatPermissionError,
+    NotFoundError,
+    OTPTimeoutError,
+    PermissionError,
+    RateLimitError,
+)
+from .inbox import Attachment, Inbox, Message
+from .redact import redact_secrets
+
+# Paketin TEK sürüm kaynağı — pyproject.toml bunu [tool.hatch.version] ile okur.
+# Yayın = burayı yükselt, başka hiçbir yeri değil.
+__version__ = "0.4.1"
+
+__all__ = [
+    "MailFlat",
+    "Inbox",
+    "Message",
+    "Attachment",
+    "MailFlatError",
+    "AuthenticationError",
+    "MailFlatPermissionError",
+    "PermissionError",  # deprecated alias of MailFlatPermissionError
+    "NotFoundError",
+    "RateLimitError",
+    "APIError",
+    "OTPTimeoutError",
+    "EncryptedInboxError",
+    "redact_secrets",
+    "__version__",
+]

mailflat-0.4.1/src/mailflat/client.py

@@ -0,0 +1,251 @@
+"""MailFlat client — a thin, typed Python wrapper around the /api/v1 automation API.
+
+One account API key (X-API-Key) creates inboxes, lists them, reads mail/OTP and sends mail.
+Every higher layer (MCP, LangChain) calls this client, so behaviour lives in one place.
+
+Connected to:
+  - imports from: mailflat.inbox, mailflat.errors (+ httpx)
+  - imported by:  mailflat.__init__
+
+Key exports:
+  - `MailFlat(api_key=..., base_url=...)` — client
+  - `.create(...) / .create_inbox(...)` — new inbox → `Inbox`
+  - `.list()` — list of `Inbox`
+  - `.inbox(address)` — attach to an existing address
+"""
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satır bilerek YORUM: docstring'e Türkçe not koymak, tam da kaçındığımız şeydi —
+# `help()` docstring'i basar, yorumu basmaz.
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+import httpx
+
+from .errors import MailFlatError, raise_for_status
+from .inbox import Inbox
+
+DEFAULT_BASE_URL = "https://mailflat.net"
+_RETRY_STATUSES = {429, 502, 503, 504}
+
+# Yalnız yan etkisi olmayan (idempotent) metotlar tekrar denenir. POST bilerek YOK:
+# /send'de MTA maili kabul edip ağ geçidi 504 dönerse, retry AYNI MAİLİ İKİNCİ KEZ yollar
+# ve kullanıcı bunu asla fark etmez. Idempotency-Key desteği gelene kadar POST tek atış.
+_IDEMPOTENT_METHODS = {"GET", "HEAD", "DELETE"}
+
+_MAX_BACKOFF = 8.0
+
+logger = logging.getLogger("mailflat")
+
+
+def _retry_after_seconds(resp: httpx.Response) -> float | None:
+    """Parse the `Retry-After` header (seconds form). Returns None when absent/unparsable."""
+    # Sunucu "12 saniye bekle" derken 1 saniyede dönmek hem 429'u tekrar yemek hem de
+    # rate limit penceresini uzatmak demekti.
+    raw = resp.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw.strip()))
+    except (TypeError, ValueError):
+        # HTTP-date biçimi de geçerli ama nadir; tahmin etmektense kendi backoff'umuza düşeriz.
+        return None
+
+
+class MailFlat:
+    """MailFlat automation API client.
+
+    >>> from mailflat import MailFlat
+    >>> mf = MailFlat(api_key="mf_live_...")
+    >>> inbox = mf.create(label="signup-test")
+    >>> inbox.address
+    'signup-test-...@mailflat.net'
+    >>> otp = inbox.wait_for_otp(timeout=30)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("MAILFLAT_API_KEY")
+        if not api_key:
+            raise MailFlatError(
+                "An API key is required. Pass MailFlat(api_key=...) or set MAILFLAT_API_KEY."
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max(0, max_retries)
+        # http_client enjeksiyonu testleri (httpx.MockTransport) kolaylaştırır.
+        self._http = http_client or httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": api_key, "User-Agent": self.user_agent()},
+            timeout=timeout,
+        )
+
+    @staticmethod
+    def user_agent() -> str:
+        """Return the `User-Agent` this client sends, e.g. `mailflat-python/0.4.0`.
+
+        Sending the version lets the server tell which SDK build is misbehaving.
+        """
+        # Sürüm burada okunuyor ki modül seviyesinde döngüsel import oluşmasın.
+        from . import __version__
+
+        return f"mailflat-python/{__version__}"
+
+    # --------------------------------------------------------------- context
+    def __enter__(self) -> "MailFlat":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # --------------------------------------------------------------- HTTP iç
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None,
+                 *, idempotent: bool | None = None) -> dict[str, Any]:
+        """`idempotent=True` → metodu ne olursa olsun retry edilebilir sayılır.
+
+        mark_read/burn POST ama tekrarı zararsız (aynı sonuç). send için ASLA verilmez:
+        tekrarlanan bir send aynı maili ikinci kez teslim eder (B-058).
+        """
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request(method, path, json=json)
+            except httpx.HTTPError as exc:  # ağ/timeout
+                raise MailFlatError(f"Network error: {exc}") from exc
+
+            retry_after = _retry_after_seconds(resp)
+            can_repeat = method.upper() in _IDEMPOTENT_METHODS if idempotent is None else idempotent
+            retriable = (
+                resp.status_code in _RETRY_STATUSES
+                and can_repeat
+                and attempt < self.max_retries
+            )
+            if retriable:
+                attempt += 1
+                delay = retry_after if retry_after is not None else min(2 ** attempt * 0.5, _MAX_BACKOFF)
+                delay = min(delay, _MAX_BACKOFF)
+                logger.debug("retrying %s %s after %s (status %s, attempt %s/%s)",
+                             method, path, delay, resp.status_code, attempt, self.max_retries)
+                time.sleep(delay)
+                continue
+
+            try:
+                data = resp.json()
+            except ValueError:
+                data = {}
+
+            if resp.status_code >= 400:
+                detail = ""
+                if isinstance(data, dict):
+                    detail = data.get("detail") or data.get("error") or ""
+                logger.debug("%s %s failed with %s: %s", method, path, resp.status_code, detail)
+                raise_for_status(resp.status_code, detail, retry_after=retry_after)
+
+            if isinstance(data, dict) and data.get("error"):  # güvenlik: 200 + error
+                raise MailFlatError(data["error"], status_code=resp.status_code)
+            return data if isinstance(data, dict) else {}
+
+    def _get(self, path: str) -> dict[str, Any]:
+        return self._request("GET", path)
+
+    def _post(self, path: str, json: dict[str, Any] | None = None,
+              *, idempotent: bool = False) -> dict[str, Any]:
+        return self._request("POST", path, json=json or {}, idempotent=idempotent)
+
+    def _delete(self, path: str) -> dict[str, Any]:
+        return self._request("DELETE", path)
+
+    def _get_bytes(self, path: str) -> httpx.Response:
+        """Raw response for binary endpoints (attachment download).
+
+        Retries on the same statuses as any other GET: this path bypassed the retry loop
+        entirely until 0.4.1, so an attachment download gave up on the first 503 while
+        every other read retried.
+        """
+        attempt = 0
+        while True:
+            try:
+                resp = self._http.request("GET", path)
+            except httpx.HTTPError as exc:
+                raise MailFlatError(f"Network error: {exc}") from exc
+            retry_after = _retry_after_seconds(resp)
+            if resp.status_code in _RETRY_STATUSES and attempt < self.max_retries:
+                attempt += 1
+                delay = retry_after if retry_after is not None else min(2 ** attempt * 0.5, _MAX_BACKOFF)
+                logger.debug("retrying GET %s after %s (status %s)", path, delay, resp.status_code)
+                time.sleep(min(delay, _MAX_BACKOFF))
+                continue
+            break
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                body = resp.json()
+                if isinstance(body, dict):
+                    detail = body.get("detail") or body.get("error") or ""
+            except ValueError:
+                pass
+            raise_for_status(resp.status_code, detail, retry_after=_retry_after_seconds(resp))
+        return resp
+
+    # --------------------------------------------------------------- public
+    def create(
+        self,
+        *,
+        prefix: str | None = None,
+        label: str | None = None,
+        subdomain: str | None = None,
+        domain: str | None = None,
+        retention_hours: int | None = None,
+    ) -> Inbox:
+        """Create a new inbox and return it as an `Inbox`.
+
+        - prefix: local part of the address (random `agent-...` when omitted)
+        - label: display name shown in the dashboard
+        - subdomain: mailflat.net subdomain (random when omitted)
+        - domain: one of your own verified BYOD domains, e.g. `acme.com`
+        - retention_hours: how long messages are kept (defaults to your plan, capped by it)
+        """
+        payload: dict[str, Any] = {}
+        if prefix is not None:
+            payload["prefix"] = prefix
+        if label is not None:
+            payload["label"] = label
+        if subdomain is not None:
+            payload["subdomain"] = subdomain
+        if domain is not None:
+            payload["domain"] = domain
+        if retention_hours is not None:
+            payload["retention_hours"] = retention_hours
+        res = self._post("/api/v1/inboxes", payload)
+        return Inbox(self, res["address"], **{k: v for k, v in res.items() if k != "address"})
+
+    # Landing snippet'leriyle birebir uyum için alias.
+    create_inbox = create
+
+    def list(self) -> list[Inbox]:
+        """Return the inboxes created with this API key."""
+        res = self._get("/api/v1/inboxes")
+        return [
+            Inbox(self, i["address"], **{k: v for k, v in i.items() if k != "address"})
+            for i in (res.get("inboxes") or [])
+        ]
+
+    def inbox(self, address: str) -> Inbox:
+        """Attach to an existing address without making an API call."""
+        return Inbox(self, address)

mailflat-0.4.1/src/mailflat/errors.py

@@ -0,0 +1,87 @@
+"""MailFlat SDK error types — maps HTTP status codes to meaningful Python exceptions.
+
+Connected to:
+  - imported by:  mailflat.client, mailflat.inbox, mailflat.__init__
+
+Key exports:
+  - `MailFlatError` — base class for every SDK error
+  - `AuthenticationError` — 401 (missing/invalid API key)
+  - `MailFlatPermissionError` — 403 (key does not own this inbox)
+  - `NotFoundError` — 404
+  - `RateLimitError` — 429 (carries `retry_after` when the server sent it)
+  - `APIError` — any other 4xx/5xx
+  - `OTPTimeoutError` — wait_for_otp / wait_for_message timed out
+  - `EncryptedInboxError` — end-to-end encrypted inbox cannot be read through the API
+"""
+# NOT: `packages/` YAYIN yüzeyi → docstring'ler İngilizce (CLAUDE.md §3).
+# Bu satırın kendisi bilerek YORUM: aynı notu docstring'e koymak tam da kaçındığımız
+# şeydi — `help()` docstring'i basar, yorumu basmaz.
+from __future__ import annotations
+
+
+class MailFlatError(Exception):
+    """Base class for every MailFlat SDK error."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class AuthenticationError(MailFlatError):
+    """401 — the API key is missing or invalid."""
+
+
+class MailFlatPermissionError(MailFlatError):
+    """403 — this API key does not own that inbox."""
+
+
+# Geriye dönük uyumluluk: 0.3.3'e kadar bu sınıfın adı `PermissionError` idi ve built-in'i
+# GÖLGELİYORDU. `except PermissionError` yazan kullanıcı, SDK'yı import etmemiş bir modülde
+# built-in'i yakalayıp bizimkini kaçırabilir (ya da tersi) — sessiz ve teşhisi zor bir hata.
+# Eski adı alias olarak bırakıyoruz ki mevcut kod kırılmasın.
+PermissionError = MailFlatPermissionError  # noqa: A001 - deprecated alias, kept for compatibility
+
+
+class NotFoundError(MailFlatError):
+    """404 — the resource does not exist."""
+
+
+class RateLimitError(MailFlatError):
+    """429 — rate limit exceeded.
+
+    `retry_after` holds the server's `Retry-After` value in seconds when it sent one,
+    so callers can wait exactly as long as the server asked instead of guessing.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None,
+                 retry_after: float | None = None) -> None:
+        super().__init__(message, status_code=status_code)
+        self.retry_after = retry_after
+
+
+class APIError(MailFlatError):
+    """An unexpected 4xx/5xx response."""
+
+
+class OTPTimeoutError(MailFlatError):
+    """No OTP (or message) arrived before the timeout elapsed."""
+
+
+class EncryptedInboxError(MailFlatError):
+    """The inbox is end-to-end encrypted, so the server cannot read its contents."""
+
+
+def raise_for_status(status_code: int, detail: str, *, retry_after: float | None = None) -> None:
+    """Raise the matching `MailFlatError` subclass for an HTTP status code."""
+    if status_code == 401:
+        raise AuthenticationError(detail or "Invalid or missing API key", status_code=status_code)
+    if status_code == 403:
+        raise MailFlatPermissionError(
+            detail or "This API key does not own that inbox", status_code=status_code)
+    if status_code == 404:
+        raise NotFoundError(detail or "Not found", status_code=status_code)
+    if status_code == 429:
+        raise RateLimitError(detail or "Rate limit exceeded", status_code=status_code,
+                             retry_after=retry_after)
+    raise APIError(detail or f"Request failed with status {status_code}", status_code=status_code)