replylayer 0.14.0__py3-none-any.whl

replylayer/resources/messages.py

@@ -0,0 +1,425 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Iterator
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from .._pagination import async_auto_paginate, sync_auto_paginate
+from ..types import Page
+
+DEFAULT_LIMIT = 50
+
+
+class SyncMessages:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def send(
+        self,
+        *,
+        body: str,
+        from_mailbox: str | None = None,
+        to: str | None = None,
+        subject: str | None = None,
+        html: str | None = None,
+        thread_id: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        attachment_ids: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Send an outbound message.
+
+        Two modes (migration 085):
+          * Fresh send — pass ``from_mailbox``, ``to``, ``subject``, ``body``.
+          * Thread continuation — pass ``thread_id`` (a thread ID or root
+            message UUID) + ``body``. ``from_mailbox``/``subject`` are derived
+            from the thread; ``to`` becomes an optional participant selector
+            (required only when the thread has >1 inbound participant). A reply
+            to a thread participant is admitted past an ``allowlist`` mailbox
+            via the thread-scoped bypass.
+
+        Sandbox accounts are subject to a 250-cumulative-send trial
+        budget. Once exhausted the API returns 403 with
+        ``code='SANDBOX_TRIAL_BUDGET_EXHAUSTED'`` and a ``details``
+        payload carrying ``feature='sandbox_cumulative_send_cap'``,
+        ``current_count``, ``max_allowed``. The cap fires from BOTH the
+        immediate-send path and the scheduled-send dispatcher (via
+        drafts) — the same code surfaces via
+        ``message.dispatch_failed.reason_code = 'SANDBOX_TRIAL_BUDGET_EXHAUSTED'``
+        for scheduled dispatches. Sandbox sends additionally have a
+        watermark footer appended to text + HTML bodies.
+        """
+        payload: dict[str, Any] = {"body": body}
+        if from_mailbox is not None:
+            payload["from_mailbox"] = from_mailbox
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if html is not None:
+            payload["html"] = html
+        if thread_id is not None:
+            payload["thread_id"] = thread_id
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+        return self._http.request("POST", "/v1/messages/send", body=payload)
+
+    def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before: str | None = None,
+        unread: bool | None = None,
+        status: str | None = None,
+        direction: str | None = None,
+        sender: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        search: str | None = None,
+        view: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Union[Page, Iterator[dict[str, Any]]]:
+        """List messages in a mailbox.
+
+        ``search`` does a substring search over subject + body. It must be at
+        least 3 characters (after Unicode NFKC normalization + trim) — the
+        server's blind-trigram index has no shorter form. A 1-2 character
+        ``search`` is rejected with HTTP 400 ``code='SEARCH_TERM_TOO_SHORT'``
+        (``details.min_search_length=3``).
+        """
+        query: dict[str, str | None] = {
+            "limit": str(limit),
+            "before": before,
+            "unread": str(unread).lower() if unread is not None else None,
+            "status": status,
+            "direction": direction,
+            "sender": sender,
+            "since": since,
+            "until": until,
+            "search": search,
+            "view": view,
+        }
+
+        def fetch_page(cursor: str | None) -> Page:
+            q = {**query, "before": cursor or query["before"]}
+            res = self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/messages", query=q)
+            msgs = res.get("messages", [])
+            next_cursor = msgs[-1]["id"] if len(msgs) == limit else None
+            return Page(data=msgs, has_more=len(msgs) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return sync_auto_paginate(fetch_page)
+        return fetch_page(None)
+
+    def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return self._http.request("GET", f"/v1/messages/{id}", query=query)
+
+    def reply(
+        self,
+        message_id: str,
+        *,
+        body: str,
+        html: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        attachment_ids: list[str] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"body": body}
+        if html is not None:
+            payload["html"] = html
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+        return self._http.request("POST", f"/v1/messages/{message_id}/reply", body=payload)
+
+    def wait(self, mailbox_id: str, *, timeout: int = 30, since: str | None = None) -> dict[str, Any]:
+        # RL-UAT-018 — `since` is the monitoring cursor anchor (strict `>`
+        # server-side); included only when set so the legacy query is unchanged.
+        query: dict[str, str] = {"timeout": str(timeout)}
+        if since is not None:
+            query["since"] = since
+        return self._http.request(
+            "GET", f"/v1/mailboxes/{mailbox_id}/messages/wait",
+            query=query,
+            timeout=float(timeout + 5),
+        )
+
+    def release(self, message_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        # G7 — optional reason persisted to audit_log.detail_json.reason.
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return self._http.request("POST", f"/v1/messages/{message_id}/release", body=body)
+
+    def block(self, message_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        # G7 — optional reason persisted to audit_log.detail_json.reason.
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return self._http.request("POST", f"/v1/messages/{message_id}/block", body=body)
+
+    def firewall_release(self, message_id: str) -> dict[str, Any]:
+        """Migration 047 — release a state='firewall_blocked' message.
+
+        Atomic: state moves to 'scanning' and the worker scanner job is
+        enqueued in the same transaction. Returns 202 immediately;
+        actual scanner verdict observed via message detail / webhook.
+        """
+        return self._http.request(
+            "POST", f"/v1/messages/{message_id}/firewall-release", body={}
+        )
+
+    def mark_read(self, message_id: str) -> dict[str, Any]:
+        """S7a — mark a single message as read.
+
+        Eligible only for inbound, visible (state NOT IN ('deleted',
+        'firewall_blocked')) rows. Outbound / deleted / firewall_blocked
+        rows return 200 no-op with the row's existing read_at. Idempotent:
+        a second eligible call returns the same read_at.
+
+        Auth: admin + agent (mailbox-scope checked) OR session cookie.
+
+        Note: as of S7a, GET /v1/messages/:id is side-effect-free and no
+        longer auto-stamps read_at. Customers must call this method
+        explicitly to advance read state.
+        """
+        return self._http.request(
+            "POST", f"/v1/messages/{message_id}/read", body={}
+        )
+
+    def approve_review(
+        self, message_id: str, *, reason: str | None = None
+    ) -> dict[str, Any]:
+        """PR 6 — approve a state='pending_review' message and dispatch.
+
+        Mirrors the /release endpoint contract: the wire status reports
+        the Mailgun dispatch outcome (release-style; 'sent' or 'blocked').
+        Audit log + webhook fire regardless of dispatch outcome.
+
+        Auth: admin API key OR session cookie. Agent keys 403 (HITL
+        approval is privileged per master spec §5.4 #7).
+
+        Optional reason (max 500 chars, server-trimmed) is persisted to
+        messages.review_reason and included in the audit_log + webhook.
+        """
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return self._http.request(
+            "POST", f"/v1/messages/{message_id}/approve", body=body
+        )
+
+    def deny_review(
+        self, message_id: str, *, reason: str | None = None
+    ) -> dict[str, Any]:
+        """PR 6 — deny a state='pending_review' message; terminal block.
+
+        No dispatch. Response is { status: 'denied', message_id }.
+        Audit log + webhook fire on commit.
+        """
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return self._http.request(
+            "POST", f"/v1/messages/{message_id}/deny", body=body
+        )
+
+
+class AsyncMessages:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def send(
+        self,
+        *,
+        body: str,
+        from_mailbox: str | None = None,
+        to: str | None = None,
+        subject: str | None = None,
+        html: str | None = None,
+        thread_id: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        attachment_ids: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Send an outbound message.
+
+        Two modes (migration 085):
+          * Fresh send — pass ``from_mailbox``, ``to``, ``subject``, ``body``.
+          * Thread continuation — pass ``thread_id`` + ``body``;
+            ``from_mailbox``/``subject`` are derived and ``to`` becomes an
+            optional participant selector.
+
+        Sandbox accounts are subject to a 250-cumulative-send trial
+        budget. Once exhausted the API returns 403 with
+        ``code='SANDBOX_TRIAL_BUDGET_EXHAUSTED'`` and a ``details``
+        payload carrying ``feature='sandbox_cumulative_send_cap'``,
+        ``current_count``, ``max_allowed``. Sandbox sends additionally
+        have a watermark footer appended to text + HTML bodies.
+        """
+        payload: dict[str, Any] = {"body": body}
+        if from_mailbox is not None:
+            payload["from_mailbox"] = from_mailbox
+        if to is not None:
+            payload["to"] = to
+        if subject is not None:
+            payload["subject"] = subject
+        if html is not None:
+            payload["html"] = html
+        if thread_id is not None:
+            payload["thread_id"] = thread_id
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+        return await self._http.request("POST", "/v1/messages/send", body=payload)
+
+    async def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before: str | None = None,
+        unread: bool | None = None,
+        status: str | None = None,
+        direction: str | None = None,
+        sender: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        search: str | None = None,
+        view: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Page | AsyncIterator[dict[str, Any]]:
+        """List messages in a mailbox.
+
+        ``search`` does a substring search over subject + body. It must be at
+        least 3 characters (after Unicode NFKC normalization + trim) — the
+        server's blind-trigram index has no shorter form. A 1-2 character
+        ``search`` is rejected with HTTP 400 ``code='SEARCH_TERM_TOO_SHORT'``
+        (``details.min_search_length=3``).
+        """
+        query: dict[str, str | None] = {
+            "limit": str(limit),
+            "before": before,
+            "unread": str(unread).lower() if unread is not None else None,
+            "status": status,
+            "direction": direction,
+            "sender": sender,
+            "since": since,
+            "until": until,
+            "search": search,
+            "view": view,
+        }
+
+        async def fetch_page(cursor: str | None) -> Page:
+            q = {**query, "before": cursor or query["before"]}
+            res = await self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/messages", query=q)
+            msgs = res.get("messages", [])
+            next_cursor = msgs[-1]["id"] if len(msgs) == limit else None
+            return Page(data=msgs, has_more=len(msgs) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return async_auto_paginate(fetch_page)
+
+        return await fetch_page(None)
+
+    async def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return await self._http.request("GET", f"/v1/messages/{id}", query=query)
+
+    async def reply(
+        self,
+        message_id: str,
+        *,
+        body: str,
+        html: str | None = None,
+        subaddress_instance_id: str | None = None,
+        subaddress_mode: str | None = None,
+        attachment_ids: list[str] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"body": body}
+        if html is not None:
+            payload["html"] = html
+        if subaddress_instance_id is not None:
+            payload["subaddress_instance_id"] = subaddress_instance_id
+        if subaddress_mode is not None:
+            payload["subaddress_mode"] = subaddress_mode
+        if attachment_ids is not None:
+            payload["attachment_ids"] = attachment_ids
+        return await self._http.request("POST", f"/v1/messages/{message_id}/reply", body=payload)
+
+    async def wait(self, mailbox_id: str, *, timeout: int = 30, since: str | None = None) -> dict[str, Any]:
+        # RL-UAT-018 — `since` is the monitoring cursor anchor (strict `>`
+        # server-side); included only when set so the legacy query is unchanged.
+        query: dict[str, str] = {"timeout": str(timeout)}
+        if since is not None:
+            query["since"] = since
+        return await self._http.request(
+            "GET", f"/v1/mailboxes/{mailbox_id}/messages/wait",
+            query=query,
+            timeout=float(timeout + 5),
+        )
+
+    async def release(self, message_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        # G7 — optional reason persisted to audit_log.detail_json.reason.
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return await self._http.request("POST", f"/v1/messages/{message_id}/release", body=body)
+
+    async def firewall_release(self, message_id: str) -> dict[str, Any]:
+        """Migration 047 — release a state='firewall_blocked' message (async)."""
+        return await self._http.request(
+            "POST", f"/v1/messages/{message_id}/firewall-release", body={}
+        )
+
+    async def block(self, message_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        # G7 — optional reason persisted to audit_log.detail_json.reason.
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return await self._http.request("POST", f"/v1/messages/{message_id}/block", body=body)
+
+    async def mark_read(self, message_id: str) -> dict[str, Any]:
+        """S7a — mark a single message as read (async). See SyncMessages.mark_read."""
+        return await self._http.request(
+            "POST", f"/v1/messages/{message_id}/read", body={}
+        )
+
+    async def approve_review(
+        self, message_id: str, *, reason: str | None = None
+    ) -> dict[str, Any]:
+        """PR 6 — approve a pending_review message and dispatch (async).
+
+        See sync SyncMessages.approve_review for the full contract.
+        """
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return await self._http.request(
+            "POST", f"/v1/messages/{message_id}/approve", body=body
+        )
+
+    async def deny_review(
+        self, message_id: str, *, reason: str | None = None
+    ) -> dict[str, Any]:
+        """PR 6 — deny a pending_review message; terminal block (async).
+
+        See sync SyncMessages.deny_review for the full contract.
+        """
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return await self._http.request(
+            "POST", f"/v1/messages/{message_id}/deny", body=body
+        )

replylayer/resources/recipients.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncRecipients:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, *, email: str) -> dict[str, Any]:
+        """Add a verified recipient (sandbox tier only).
+
+        Sandbox accounts are subject to a verified-recipient ramp: 5 in
+        the first 72 hours, 25 thereafter. When the cap is hit, the API
+        returns 403 with ``code='TIER_LIMIT'`` and a ``details`` payload
+        carrying ``feature='sandbox_recipient_confirmation_required'``,
+        ``current_count``, ``max_allowed``, and (in the pre-ramp window)
+        ``ramp_until`` (ISO timestamp). Catch with :class:`ForbiddenError`
+        and inspect ``err.details`` for the actionable fields.
+        """
+        return self._http.request("POST", "/v1/recipients", body={"email": email})
+
+    def list(self) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/recipients")
+
+    def delete(self, id: str) -> None:
+        self._http.request("DELETE", f"/v1/recipients/{id}")
+
+    def resend(self, id: str) -> dict[str, Any]:
+        return self._http.request("POST", f"/v1/recipients/{id}/resend")
+
+
+class AsyncRecipients:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, *, email: str) -> dict[str, Any]:
+        """Add a verified recipient (sandbox tier only).
+
+        Sandbox accounts are subject to a verified-recipient ramp: 5 in
+        the first 72 hours, 25 thereafter. When the cap is hit, the API
+        returns 403 with ``code='TIER_LIMIT'`` and a ``details`` payload
+        carrying ``feature='sandbox_recipient_confirmation_required'``,
+        ``current_count``, ``max_allowed``, and (in the pre-ramp window)
+        ``ramp_until`` (ISO timestamp). Catch with :class:`ForbiddenError`
+        and inspect ``err.details`` for the actionable fields.
+        """
+        return await self._http.request("POST", "/v1/recipients", body={"email": email})
+
+    async def list(self) -> dict[str, Any]:
+        return await self._http.request("GET", "/v1/recipients")
+
+    async def delete(self, id: str) -> None:
+        await self._http.request("DELETE", f"/v1/recipients/{id}")
+
+    async def resend(self, id: str) -> dict[str, Any]:
+        return await self._http.request("POST", f"/v1/recipients/{id}/resend")

replylayer/resources/suppressions.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._http import AsyncHttpClient, SyncHttpClient
+
+
+class SyncSuppressions:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        reason: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+        all: bool | None = None,  # noqa: A002 — match REST query name
+    ) -> dict[str, Any]:
+        query: dict[str, Any] = {}
+        if reason is not None:
+            query["reason"] = reason
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        if all:
+            query["all"] = "true"
+        return self._http.request("GET", "/v1/suppressions", query=query)
+
+    def add(self, *, email: str) -> dict[str, Any]:
+        """
+        Add an address to the do-not-contact list. Server forces
+        ``reason='manual'`` + ``source='customer'``. Idempotent — a repeat
+        call returns ``already_existed: true`` with no second audit row and
+        no second webhook delivery. Agent + admin keys both accepted.
+        """
+        return self._http.request("POST", "/v1/suppressions", body={"email": email})
+
+    def add_bulk(self, *, emails: list[str]) -> dict[str, Any]:
+        """
+        Add up to 1000 addresses in one request. Returns partial-success
+        buckets: ``added``, ``already_existed``, ``invalid``. Server normalizes
+        (trim + lowercase) and dedupes (case-variant-aware) before validation.
+        Rate-limited by emails added (entry-count), not requests made.
+        """
+        return self._http.request("POST", "/v1/suppressions/bulk", body={"emails": emails})
+
+    def delete(self, email: str) -> dict[str, Any]:
+        return self._http.request("DELETE", f"/v1/suppressions/{quote(email, safe='')}")
+
+
+class AsyncSuppressions:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        *,
+        reason: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+        all: bool | None = None,  # noqa: A002
+    ) -> dict[str, Any]:
+        query: dict[str, Any] = {}
+        if reason is not None:
+            query["reason"] = reason
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        if all:
+            query["all"] = "true"
+        return await self._http.request("GET", "/v1/suppressions", query=query)
+
+    async def add(self, *, email: str) -> dict[str, Any]:
+        return await self._http.request("POST", "/v1/suppressions", body={"email": email})
+
+    async def add_bulk(self, *, emails: list[str]) -> dict[str, Any]:
+        return await self._http.request("POST", "/v1/suppressions/bulk", body={"emails": emails})
+
+    async def delete(self, email: str) -> dict[str, Any]:
+        return await self._http.request("DELETE", f"/v1/suppressions/{quote(email, safe='')}")

replylayer/resources/threads.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Iterator
+from urllib.parse import quote
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from .._pagination import async_auto_paginate, sync_auto_paginate
+from ..types import Page
+
+DEFAULT_LIMIT = 50
+
+
+class SyncThreads:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before_ts: str | None = None,
+        since_ts: str | None = None,
+        has_inbound: bool | None = None,
+        include_firewall_blocked: bool = False,
+        view: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Union[Page, Iterator[dict[str, Any]]]:
+        def fetch_page(cursor: str | None) -> Page:
+            query: dict[str, str | None] = {
+                "limit": str(limit),
+                "before_ts": cursor or before_ts,
+                "since_ts": since_ts,
+                "has_inbound": ("true" if has_inbound else "false") if has_inbound is not None else None,
+                "include_firewall_blocked": "true" if include_firewall_blocked else None,
+                "view": view,
+            }
+            res = self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/threads", query=query)
+            threads = res.get("threads", [])
+            next_cursor = threads[-1]["last_message_at"] if len(threads) == limit else None
+            return Page(data=threads, has_more=len(threads) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return sync_auto_paginate(fetch_page)
+        return fetch_page(None)
+
+    def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return self._http.request("GET", f"/v1/threads/{quote(id, safe='')}", query=query)
+
+    def mark_read(self, mailbox_id: str, thread_id: str) -> dict[str, Any]:
+        """S7a — bulk-mark every visible inbound unread message as read.
+
+        mailbox_id accepts a name OR UUID. thread_id is the thread key
+        (Message-Id or message UUID for standalone NULL-thread rows).
+
+        Distinct 404 codes:
+          * 'Mailbox not found' — mailbox doesn't exist or wrong account
+          * 'Thread not found'  — mailbox exists but thread doesn't
+
+        Returns marked_count of rows newly stamped this call (excludes
+        already-read, outbound, deleted, firewall_blocked). A thread with
+        all messages already read returns 200 marked_count: 0 (NOT 404).
+        """
+        return self._http.request(
+            "POST",
+            f"/v1/mailboxes/{quote(mailbox_id, safe='')}/threads/{quote(thread_id, safe='')}/read",
+            body={},
+        )
+
+
+class AsyncThreads:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        mailbox_id: str,
+        *,
+        limit: int = DEFAULT_LIMIT,
+        before_ts: str | None = None,
+        since_ts: str | None = None,
+        has_inbound: bool | None = None,
+        include_firewall_blocked: bool = False,
+        view: str | None = None,
+        auto_paginate: bool = False,
+    ) -> Page | AsyncIterator[dict[str, Any]]:
+        async def fetch_page(cursor: str | None) -> Page:
+            query: dict[str, str | None] = {
+                "limit": str(limit),
+                "before_ts": cursor or before_ts,
+                "since_ts": since_ts,
+                "has_inbound": ("true" if has_inbound else "false") if has_inbound is not None else None,
+                "include_firewall_blocked": "true" if include_firewall_blocked else None,
+                "view": view,
+            }
+            res = await self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/threads", query=query)
+            threads = res.get("threads", [])
+            next_cursor = threads[-1]["last_message_at"] if len(threads) == limit else None
+            return Page(data=threads, has_more=len(threads) == limit, cursor=next_cursor)
+
+        if auto_paginate:
+            return async_auto_paginate(fetch_page)
+
+        return await fetch_page(None)
+
+    async def get(self, id: str, *, view: str | None = None, body_format: str | None = None) -> dict[str, Any]:
+        query = {k: v for k, v in {"view": view, "body_format": body_format}.items() if v is not None}
+        return await self._http.request("GET", f"/v1/threads/{quote(id, safe='')}", query=query)
+
+    async def mark_read(self, mailbox_id: str, thread_id: str) -> dict[str, Any]:
+        """S7a — bulk-mark every visible inbound unread message (async). See SyncThreads.mark_read."""
+        return await self._http.request(
+            "POST",
+            f"/v1/mailboxes/{quote(mailbox_id, safe='')}/threads/{quote(thread_id, safe='')}/read",
+            body={},
+        )