replylayer 0.16.0__tar.gz → 0.18.0__tar.gz

{replylayer-0.16.0 → replylayer-0.18.0}/.gitignore

@@ -52,3 +52,7 @@ plans/fault-briefings/
 # under audits/ — these are signed-verdict-anchored evidence per
 # plans/granite-guardian-failover-saturation-stress-test.md §11.
 !audits/**/*.log
+uat-grading-results*.json
+
+# Scanner eval run outputs (corpora are tracked, results are not)
+packages/scanner/src/eval/*-results.json

{replylayer-0.16.0 → replylayer-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: replylayer
-Version: 0.16.0
+Version: 0.18.0
 Summary: Official Python SDK for ReplyLayer — email for AI agents
 License-Expression: MIT
 Keywords: agent,ai,email,mailbox,replylayer,sdk,webhook
@@ -126,7 +126,7 @@ contract — read it before relying on retries:
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
 | `rl.suppressions` | `list`, `delete` |
 | `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
-| `rl.account` | `get_usage` |
+| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning` |
 | `rl.health` | `check` |
 
 *`api_keys.rotate()` revokes the calling API key and returns a new one. After calling it, this SDK instance's key is invalidated — create a new `ReplyLayer` instance with the returned key.
@@ -152,7 +152,7 @@ The send/reply/draft-send response carries two additive, nullable keys that expl
 By default `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. Pass `async_dispatch=True` to `drafts.send()` to send the `Prefer: respond-async` hint. **The hint is advisory** — the server returns a `202 AsyncSendAck` only when `OUTBOUND_ASYNC_DISPATCH_ENABLED` is on; otherwise it ignores the hint and returns a normal `SendMessageResponse`. **Always branch on the result**: `result["status"] == "queued_for_dispatch"` ⇒ `AsyncSendAck`, otherwise `SendMessageResponse`. Poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. Attachment-bearing drafts fail closed on the async path (`400 ATTACHMENTS_REQUIRE_SYNC_SEND`). (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
 
 The send endpoint raises `ReplyLayerError` with distinct `.code` values on 409:
-- `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan` and, when a policy/HITL decision drove the hold, `hold_context`.
+- `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan`, `releasable` (`True` for a `quarantine` hold the customer can release via `POST /v1/drafts/:id/release-and-send`, `False` for a terminal `block`), and, when a policy/HITL decision drove the hold, `hold_context`.
 - `DRAFT_ALREADY_SENT` — the draft was already sent (race or retry after success).
 
 ```python
@@ -167,7 +167,7 @@ except ReplyLayerError as err:
 
 ## Outbound attachments (Pro+)
 
-Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** (a Pro+, session-gated dashboard action) — uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
+Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** by a human account owner in the dashboard (Pro+, mailbox Settings page, TOTP/password re-auth). Once enabled, API keys can send attachments; uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
 
 ```python
 import time
@@ -426,6 +426,23 @@ Webhook deliveries are deduped server-side to at most one per `(account, mailbox
 
 The MCP tool `list_allowlist_blocked_attempts` exposes the same view to agents — read-only by design. There is no dismiss-attempt tool (the containment boundary would be moot if an agent could clear its own rejection history).
 
+## Malicious link scanning (URL reputation)
+
+Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). It is off by default and opt-in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
+
+Pass the version you are acknowledging explicitly; the SDK does not auto-fetch it, so the consent is recorded against a version your code chose:
+
+```python
+status = rl.account.get_link_scanning_status()
+# {"active", "accepted_version", "current_version", "privacy_ok"}
+
+if not status["active"] and status["privacy_ok"]:
+    res = rl.account.enable_link_scanning(accept_web_risk_version=status["current_version"])
+    # res["url_reputation"]["active"] is True; res["disclosure"]["notice"] / ["advisory_url"]
+```
+
+If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
+
 ## Mailbox identifiers
 
 Every SDK method that takes a `mailbox_id` argument accepts **either the mailbox's UUID or its name**. The server resolves names against the authenticated account's active mailboxes. `rl.messages.list("support-bot")` and `rl.messages.list("a1b2-…")` are equivalent.
@@ -470,7 +487,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see [`docs/webhooks.md`](../../docs/webhooks.md).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
 
 ```python
 from replylayer import verify_webhook_signature
@@ -483,6 +500,19 @@ verify_webhook_signature(
 )
 ```
 
+Once verified, parse and dispatch on the event type. **The discriminator field is `event`, not `type`:**
+
+```python
+import json
+
+payload = json.loads(request.body)
+# payload["event"] is the discriminator — NOT payload["type"]
+if payload["event"] == "message.received":
+    # handle inbound message
+elif payload["event"] == "message.dispatch_failed":
+    # handle failed outbound send
+```
+
 ## Context managers
 
 Both clients support context managers to properly close connection pools:

{replylayer-0.16.0 → replylayer-0.18.0}/README.md

@@ -109,7 +109,7 @@ contract — read it before relying on retries:
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
 | `rl.suppressions` | `list`, `delete` |
 | `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
-| `rl.account` | `get_usage` |
+| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning` |
 | `rl.health` | `check` |
 
 *`api_keys.rotate()` revokes the calling API key and returns a new one. After calling it, this SDK instance's key is invalidated — create a new `ReplyLayer` instance with the returned key.
@@ -135,7 +135,7 @@ The send/reply/draft-send response carries two additive, nullable keys that expl
 By default `drafts.send()`, `messages.send()`, and `messages.reply()` return only once the scanner verdict is known, with `scan` and `hold_context` inline. Pass `async_dispatch=True` to `drafts.send()` to send the `Prefer: respond-async` hint. **The hint is advisory** — the server returns a `202 AsyncSendAck` only when `OUTBOUND_ASYNC_DISPATCH_ENABLED` is on; otherwise it ignores the hint and returns a normal `SendMessageResponse`. **Always branch on the result**: `result["status"] == "queued_for_dispatch"` ⇒ `AsyncSendAck`, otherwise `SendMessageResponse`. Poll `messages.get(message_id)` (or handle the lifecycle webhook) until `state` is terminal. Attachment-bearing drafts fail closed on the async path (`400 ATTACHMENTS_REQUIRE_SYNC_SEND`). (`messages.wait()` is a mailbox long-poll for new *inbound* mail, not a way to observe a specific message by ID.)
 
 The send endpoint raises `ReplyLayerError` with distinct `.code` values on 409:
-- `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan` and, when a policy/HITL decision drove the hold, `hold_context`.
+- `DRAFT_REJECTED_BY_RESCAN` — send-time scan flipped the verdict to `block`/`quarantine`. The draft stays in `draft` state; edit the body and retry. `err.details` carries `scan`, `releasable` (`True` for a `quarantine` hold the customer can release via `POST /v1/drafts/:id/release-and-send`, `False` for a terminal `block`), and, when a policy/HITL decision drove the hold, `hold_context`.
 - `DRAFT_ALREADY_SENT` — the draft was already sent (race or retry after success).
 
 ```python
@@ -150,7 +150,7 @@ except ReplyLayerError as err:
 
 ## Outbound attachments (Pro+)
 
-Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** (a Pro+, session-gated dashboard action) — uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
+Attaching a file is a **two-phase** flow: upload the bytes to stage a handle, then reference `handle["id"]` in a send/reply/draft `attachment_ids` list. Every attachment is scanned (byte-level family validation + AV + secrets/PII over extracted text **and** filename) before it leaves. The mailbox must have outbound attachments **explicitly enabled** by a human account owner in the dashboard (Pro+, mailbox Settings page, TOTP/password re-auth). Once enabled, API keys can send attachments; uploads to a non-enabled mailbox raise `ForbiddenError` with `code="OUTBOUND_ATTACHMENTS_DISABLED"`.
 
 ```python
 import time
@@ -409,6 +409,23 @@ Webhook deliveries are deduped server-side to at most one per `(account, mailbox
 
 The MCP tool `list_allowlist_blocked_attempts` exposes the same view to agents — read-only by design. There is no dismiss-attempt tool (the containment boundary would be moot if an agent could clear its own rejection history).
 
+## Malicious link scanning (URL reputation)
+
+Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). It is off by default and opt-in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
+
+Pass the version you are acknowledging explicitly; the SDK does not auto-fetch it, so the consent is recorded against a version your code chose:
+
+```python
+status = rl.account.get_link_scanning_status()
+# {"active", "accepted_version", "current_version", "privacy_ok"}
+
+if not status["active"] and status["privacy_ok"]:
+    res = rl.account.enable_link_scanning(accept_web_risk_version=status["current_version"])
+    # res["url_reputation"]["active"] is True; res["disclosure"]["notice"] / ["advisory_url"]
+```
+
+If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
+
 ## Mailbox identifiers
 
 Every SDK method that takes a `mailbox_id` argument accepts **either the mailbox's UUID or its name**. The server resolves names against the authenticated account's active mailboxes. `rl.messages.list("support-bot")` and `rl.messages.list("a1b2-…")` are equivalent.
@@ -453,7 +470,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see [`docs/webhooks.md`](../../docs/webhooks.md).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
 
 ```python
 from replylayer import verify_webhook_signature
@@ -466,6 +483,19 @@ verify_webhook_signature(
 )
 ```
 
+Once verified, parse and dispatch on the event type. **The discriminator field is `event`, not `type`:**
+
+```python
+import json
+
+payload = json.loads(request.body)
+# payload["event"] is the discriminator — NOT payload["type"]
+if payload["event"] == "message.received":
+    # handle inbound message
+elif payload["event"] == "message.dispatch_failed":
+    # handle failed outbound send
+```
+
 ## Context managers
 
 Both clients support context managers to properly close connection pools:

{replylayer-0.16.0 → replylayer-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.16.0"
+version = "0.18.0"
 description = "Official Python SDK for ReplyLayer — email for AI agents"
 readme = "README.md"
 license = "MIT"

{replylayer-0.16.0 → replylayer-0.18.0}/replylayer/__init__.py

@@ -1,5 +1,6 @@
 from ._client import ReplyLayer, AsyncReplyLayer
 from ._http import RetryInfo
+from .resources.messages import IdempotencyReplayResult
 from .resources.webhooks import verify_webhook_signature
 from .errors import (
     ReplyLayerError,
@@ -57,6 +58,10 @@ from .types import (
     WebRiskLearnMore,
     WebRiskWarning,
     WebRiskThreatType,
+    LinkScanningStatus,
+    EnableLinkScanningResponse,
+    EnableLinkScanningDisclosure,
+    AgentSafetyContext,
     MessageReceivedSafetySignal,
     MessageReceivedWebhookPayload,
     # PR 6 — HITL review queue webhook payload types.
@@ -76,7 +81,7 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.16.0"
+__version__ = "0.18.0"
 
 __all__ = [
     # WS1 — star response types (0.16.0).
@@ -84,6 +89,8 @@ __all__ = [
     "ThreadStarResponse",
     # WS6-SDK — async optimistic-ack (0.16.0).
     "AsyncSendAck",
+    # Track 1 — non-throwing idempotency replay probe result.
+    "IdempotencyReplayResult",
     "ReplyLayer",
     "AsyncReplyLayer",
     "RetryInfo",
@@ -132,6 +139,10 @@ __all__ = [
     "WebRiskLearnMore",
     "WebRiskWarning",
     "WebRiskThreatType",
+    "LinkScanningStatus",
+    "EnableLinkScanningResponse",
+    "EnableLinkScanningDisclosure",
+    "AgentSafetyContext",
     "MessageReceivedSafetySignal",
     "MessageReceivedWebhookPayload",
     # PR 6 — HITL review queue.

{replylayer-0.16.0 → replylayer-0.18.0}/replylayer/_http.py

@@ -9,7 +9,7 @@ import httpx
 
 from .errors import ReplyLayerError, error_from_response
 
-_VERSION = "0.16.0"
+_VERSION = "0.18.0"
 _USER_AGENT = f"replylayer-sdk-py/{_VERSION}"
 _PROTECTED_HEADER_KEYS = frozenset({"authorization", "content-type", "user-agent"})
 

replylayer-0.18.0/replylayer/resources/account.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, SyncHttpClient
+from ..errors import ReplyLayerError
+from ..types import (
+    EnableLinkScanningResponse,
+    LinkScanningStatus,
+    QuotaResponse,
+    UsageResponse,
+)
+
+# Raised when the deployed API predates the malicious-link-scanning surface and
+# omits the url_reputation block from GET /v1/auth/me. Mirrors the TS SDK / CLI
+# clear "API outdated" error instead of leaking a raw KeyError.
+_LINK_SCANNING_UNSUPPORTED_MSG = (
+    "Server did not return link-scanning status; the API may be outdated."
+)
+
+
+class SyncAccount:
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def get_usage(self) -> UsageResponse:
+        return self._http.request("GET", "/v1/accounts/usage")
+
+    def get_quota(self) -> QuotaResponse:
+        return self._http.request("GET", "/v1/accounts/quota")
+
+    def get_link_scanning_status(self) -> LinkScanningStatus:
+        """Malicious link scanning (URL reputation, Google Web Risk) status.
+
+        Reads the ``url_reputation`` block off GET /v1/auth/me. Works with any key.
+        """
+        me = self._http.request("GET", "/v1/auth/me")
+        if "url_reputation" not in me:
+            raise ReplyLayerError(0, "LINK_SCANNING_UNSUPPORTED", _LINK_SCANNING_UNSUPPORTED_MSG)
+        return me["url_reputation"]
+
+    def enable_link_scanning(self, accept_web_risk_version: str) -> EnableLinkScanningResponse:
+        """Enable malicious link scanning.
+
+        Pass the disclaimer version you are acknowledging (from
+        ``get_link_scanning_status()["current_version"]``) — the consent is explicit.
+        Requires an admin key or session (agent keys get 403). The response includes
+        the disclosure you accepted.
+        """
+        return self._http.request(
+            "POST",
+            "/v1/accounts/url-reputation",
+            body={"accept_web_risk_version": accept_web_risk_version},
+        )
+
+    def export(self) -> dict[str, Any]:
+        """GDPR Art. 20 data portability export — the full account-data object."""
+        return self._http.request("GET", "/v1/accounts/export")
+
+
+class AsyncAccount:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get_usage(self) -> UsageResponse:
+        return await self._http.request("GET", "/v1/accounts/usage")
+
+    async def get_quota(self) -> QuotaResponse:
+        return await self._http.request("GET", "/v1/accounts/quota")
+
+    async def get_link_scanning_status(self) -> LinkScanningStatus:
+        """Malicious link scanning (URL reputation, Google Web Risk) status.
+
+        Reads the ``url_reputation`` block off GET /v1/auth/me. Works with any key.
+        """
+        me = await self._http.request("GET", "/v1/auth/me")
+        if "url_reputation" not in me:
+            raise ReplyLayerError(0, "LINK_SCANNING_UNSUPPORTED", _LINK_SCANNING_UNSUPPORTED_MSG)
+        return me["url_reputation"]
+
+    async def enable_link_scanning(self, accept_web_risk_version: str) -> EnableLinkScanningResponse:
+        """Enable malicious link scanning.
+
+        Pass the disclaimer version you are acknowledging (from
+        ``get_link_scanning_status()["current_version"]``) — the consent is explicit.
+        Requires an admin key or session (agent keys get 403). The response includes
+        the disclosure you accepted.
+        """
+        return await self._http.request(
+            "POST",
+            "/v1/accounts/url-reputation",
+            body={"accept_web_risk_version": accept_web_risk_version},
+        )
+
+    async def export(self) -> dict[str, Any]:
+        """GDPR Art. 20 data portability export — the full account-data object."""
+        return await self._http.request("GET", "/v1/accounts/export")

{replylayer-0.16.0 → replylayer-0.18.0}/replylayer/resources/attachments.py

@@ -51,8 +51,9 @@ class SyncAttachments:
         content_type: str | None = None,
     ) -> UploadAttachmentResponse:
         """Stage an outbound attachment (phase 1). Returns an opaque handle;
-        pass ``handle["id"]`` in a send/reply/draft ``attachment_ids`` list. The
-        mailbox must have outbound attachments enabled (Pro+). The returned
+        pass ``handle["id"]`` in a send/reply/draft ``attachment_ids`` list. A
+        human account owner must first enable outbound attachments for the
+        mailbox in the dashboard (Pro+, TOTP/password re-auth). The returned
         ``content_scan_status`` is ``"pending"`` — poll :meth:`get_upload` until
         terminal before referencing the handle, or the send fails with
         ``ATTACHMENT_SCAN_PENDING``.

{replylayer-0.16.0 → replylayer-0.18.0}/replylayer/resources/drafts.py

@@ -146,8 +146,14 @@ class SyncDrafts:
             q = {**query, "before": cursor or query["before"]}
             res = self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/drafts", query=q)
             drafts = res.get("drafts", [])
-            next_cursor = drafts[-1]["id"] if len(drafts) == limit else None
-            return Page(data=drafts, has_more=len(drafts) == limit, cursor=next_cursor)
+            # UAT-22 — consume the server's authoritative `has_more` (#296) instead
+            # of the old `len(drafts) == limit` inference, which over-reported at
+            # the exact-`limit` boundary. Derive `next_cursor` FROM has_more so we
+            # only advance when the server says another page exists. Defensive
+            # default `False` for a pre-#296 server that omits the field.
+            has_more = res.get("has_more") is True
+            next_cursor = drafts[-1]["id"] if has_more and drafts else None
+            return Page(data=drafts, has_more=has_more, cursor=next_cursor)
 
         if auto_paginate:
             return sync_auto_paginate(fetch_page)
@@ -299,8 +305,14 @@ class AsyncDrafts:
             q = {**query, "before": cursor or query["before"]}
             res = await self._http.request("GET", f"/v1/mailboxes/{mailbox_id}/drafts", query=q)
             drafts = res.get("drafts", [])
-            next_cursor = drafts[-1]["id"] if len(drafts) == limit else None
-            return Page(data=drafts, has_more=len(drafts) == limit, cursor=next_cursor)
+            # UAT-22 — consume the server's authoritative `has_more` (#296) instead
+            # of the old `len(drafts) == limit` inference (byte-identical to the
+            # sync method). A sync-only fix would leave this async path still
+            # over-reporting at the exact-`limit` boundary. Defensive default
+            # `False` for a pre-#296 server that omits the field.
+            has_more = res.get("has_more") is True
+            next_cursor = drafts[-1]["id"] if has_more and drafts else None
+            return Page(data=drafts, has_more=has_more, cursor=next_cursor)
 
         if auto_paginate:
             return async_auto_paginate(fetch_page)

{replylayer-0.16.0 → replylayer-0.18.0}/replylayer/resources/messages.py

@@ -1,13 +1,72 @@
 from __future__ import annotations
 
-from typing import Any, AsyncIterator, Iterator
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Iterator, Literal
 
 from .._http import AsyncHttpClient, SyncHttpClient
 from .._pagination import async_auto_paginate, sync_auto_paginate
+from ..errors import ReplyLayerError
 from ..types import MessageStarResponse, Page
 
 DEFAULT_LIMIT = 50
 
+# Track 1 §3a — wire codes the replay-probe (GET /v1/messages/idempotency)
+# returns on a 409. Matched on ``ReplyLayerError.code`` verbatim (NOT a
+# substring-of-message match), since the base client exposes the wire code.
+_IDEMPOTENT_REQUEST_IN_FLIGHT = "IDEMPOTENT_REQUEST_IN_FLIGHT"
+_IDEMPOTENT_REQUEST_NOT_PROVEN_SENT = "IDEMPOTENT_REQUEST_NOT_PROVEN_SENT"
+_IDEMPOTENCY_KEY_BOUND_TO_DRAFT = "IDEMPOTENCY_KEY_BOUND_TO_DRAFT"
+
+
+@dataclass
+class IdempotencyReplayResult:
+    """Discriminated result of the non-throwing replay probe (Track 1 §3a).
+
+    ``kind`` is the tag:
+      * ``'miss'``            — 404, no prior keyed row. Proceed: upload + keyed POST.
+      * ``'replay'``          — 200, a prior result exists. ``message`` holds it.
+      * ``'in_flight'``       — 409 IDEMPOTENT_REQUEST_IN_FLIGHT. ``retry_after``
+                                (seconds) is sourced from the response BODY
+                                ``details.retry_after`` (NOT the ``Retry-After``
+                                header — the base client only parses that for 429).
+      * ``'not_proven_sent'`` — 409 IDEMPOTENT_REQUEST_NOT_PROVEN_SENT.
+      * ``'bound_to_draft'``  — 409 IDEMPOTENCY_KEY_BOUND_TO_DRAFT (cross-namespace).
+    """
+
+    kind: Literal["miss", "replay", "in_flight", "not_proven_sent", "bound_to_draft"]
+    message: dict[str, Any] | None = None
+    retry_after: int | None = None
+
+
+def _classify_idempotency_probe_error(
+    err: ReplyLayerError,
+) -> IdempotencyReplayResult | None:
+    """Map a raised probe error to a discriminated result, or ``None`` to
+    signal the caller should RE-RAISE (every other non-2xx: 401/403/500/…).
+
+    Matched on the wire ``status_code`` + ``code`` (the typed error exposes
+    both), never on a string-in-message match.
+    """
+    if err.status_code == 404:
+        return IdempotencyReplayResult(kind="miss")
+    if err.status_code == 409:
+        if err.code == _IDEMPOTENT_REQUEST_IN_FLIGHT:
+            retry_after: int | None = None
+            details = err.details
+            if isinstance(details, dict):
+                raw = details.get("retry_after")
+                if isinstance(raw, bool):
+                    raw = None
+                if isinstance(raw, (int, float)):
+                    retry_after = int(raw)
+            return IdempotencyReplayResult(kind="in_flight", retry_after=retry_after)
+        if err.code == _IDEMPOTENT_REQUEST_NOT_PROVEN_SENT:
+            return IdempotencyReplayResult(kind="not_proven_sent")
+        if err.code == _IDEMPOTENCY_KEY_BOUND_TO_DRAFT:
+            return IdempotencyReplayResult(kind="bound_to_draft")
+    # Any other non-2xx (401/403/500/other-409-code) → re-raise.
+    return None
+
 
 class SyncMessages:
     def __init__(self, http: SyncHttpClient) -> None:
@@ -25,6 +84,7 @@ class SyncMessages:
         subaddress_instance_id: str | None = None,
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
         """Send an outbound message.
 
@@ -37,6 +97,13 @@ class SyncMessages:
             to a thread participant is admitted past an ``allowlist`` mailbox
             via the thread-scoped bypass.
 
+        ``idempotency_key`` (Track 1) makes a retried same-key immediate send
+        produce at most one email + one charge: the server replays the prior
+        message instead of re-sending. The key travels in the ``Idempotency-Key``
+        request header; it is permanent (no expiry) and must be a stable string
+        per send intent. See :meth:`get_idempotency_replay` for the read-only
+        probe the attachment-taking wrappers use before re-uploading.
+
         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``
@@ -65,7 +132,12 @@ class SyncMessages:
             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)
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+        return self._http.request(
+            "POST", "/v1/messages/send", body=payload, extra_headers=extra_headers
+        )
 
     def list(
         self,
@@ -136,7 +208,15 @@ class SyncMessages:
         subaddress_instance_id: str | None = None,
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
+        """Reply to an inbound message.
+
+        ``idempotency_key`` (Track 1) makes a retried same-key reply produce at
+        most one email + one charge — the server replays the prior message
+        instead of re-sending. The key travels in the ``Idempotency-Key``
+        request header. See :meth:`get_idempotency_replay`.
+        """
         payload: dict[str, Any] = {"body": body}
         if html is not None:
             payload["html"] = html
@@ -146,7 +226,49 @@ class SyncMessages:
             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)
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+        return self._http.request(
+            "POST",
+            f"/v1/messages/{message_id}/reply",
+            body=payload,
+            extra_headers=extra_headers,
+        )
+
+    def get_idempotency_replay(self, key: str) -> "IdempotencyReplayResult":
+        """Probe whether an immediate-send/reply idempotency key already has a
+        prior result, WITHOUT side effects (Track 1, §3a).
+
+        The MCP/CLI attachment wrappers call this BEFORE re-uploading
+        attachments (or re-fetching the original message) on a same-key retry,
+        so a retry whose local file is gone still replays the prior result
+        instead of dying in local preflight.
+
+        Non-throwing + discriminated: the base client raises on every non-2xx,
+        but the load-bearing 404 *miss* (the common "no prior, proceed" case)
+        and the three 409 outcomes are caught here and returned as an
+        :class:`IdempotencyReplayResult` (``.kind`` one of ``'miss'``,
+        ``'replay'``, ``'in_flight'``, ``'not_proven_sent'``,
+        ``'bound_to_draft'``). Every OTHER non-2xx (401/403/500/other-409)
+        re-raises the original error.
+
+        The key travels in the ``Idempotency-Key`` request header (keys are
+        arbitrary client strings that may contain ``/``, ``?``, ``#`` — a header
+        sidesteps URL-encoding hazards).
+        """
+        try:
+            message = self._http.request(
+                "GET",
+                "/v1/messages/idempotency",
+                extra_headers={"Idempotency-Key": key},
+            )
+        except ReplyLayerError as err:
+            result = _classify_idempotency_probe_error(err)
+            if result is None:
+                raise
+            return result
+        return IdempotencyReplayResult(kind="replay", message=message)
 
     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 `>`
@@ -268,6 +390,7 @@ class AsyncMessages:
         subaddress_instance_id: str | None = None,
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
         """Send an outbound message.
 
@@ -277,6 +400,11 @@ class AsyncMessages:
             ``from_mailbox``/``subject`` are derived and ``to`` becomes an
             optional participant selector.
 
+        ``idempotency_key`` (Track 1) makes a retried same-key immediate send
+        produce at most one email + one charge — the server replays the prior
+        message instead of re-sending. The key travels in the ``Idempotency-Key``
+        request header. See :meth:`get_idempotency_replay`.
+
         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``
@@ -301,7 +429,12 @@ class AsyncMessages:
             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)
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+        return await self._http.request(
+            "POST", "/v1/messages/send", body=payload, extra_headers=extra_headers
+        )
 
     async def list(
         self,
@@ -373,7 +506,13 @@ class AsyncMessages:
         subaddress_instance_id: str | None = None,
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
+        """Reply to an inbound message (async). See SyncMessages.reply.
+
+        ``idempotency_key`` (Track 1) makes a retried same-key reply produce at
+        most one email + one charge. See :meth:`get_idempotency_replay`.
+        """
         payload: dict[str, Any] = {"body": body}
         if html is not None:
             payload["html"] = html
@@ -383,7 +522,35 @@ class AsyncMessages:
             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)
+        extra_headers: dict[str, str] | None = None
+        if idempotency_key is not None:
+            extra_headers = {"Idempotency-Key": idempotency_key}
+        return await self._http.request(
+            "POST",
+            f"/v1/messages/{message_id}/reply",
+            body=payload,
+            extra_headers=extra_headers,
+        )
+
+    async def get_idempotency_replay(self, key: str) -> "IdempotencyReplayResult":
+        """Async probe of an immediate-send/reply idempotency key (Track 1, §3a).
+
+        Non-throwing + discriminated — see SyncMessages.get_idempotency_replay
+        for the full contract. The key travels in the ``Idempotency-Key``
+        request header.
+        """
+        try:
+            message = await self._http.request(
+                "GET",
+                "/v1/messages/idempotency",
+                extra_headers={"Idempotency-Key": key},
+            )
+        except ReplyLayerError as err:
+            result = _classify_idempotency_probe_error(err)
+            if result is None:
+                raise
+            return result
+        return IdempotencyReplayResult(kind="replay", message=message)
 
     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 `>`