replylayer 0.18.0__tar.gz → 0.21.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: replylayer
-Version: 0.18.0
+Version: 0.21.0
 Summary: Official Python SDK for ReplyLayer — email for AI agents
 License-Expression: MIT
 Keywords: agent,ai,email,mailbox,replylayer,sdk,webhook

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

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

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

@@ -13,8 +13,16 @@ from .errors import (
     # Migration 040 — scheduled-send error surface.
     SchedulingError,
     TimezoneRequiredError,
+    # Governed Email-Effect Contract v1 (Track 2) — strict-outcome errors.
+    EmailEffectError,
+    EmailEffectRejectedError,
+    EmailEffectHeldError,
+    EmailEffectRetryableError,
 )
 from .types import (
+    # Message delete response (0.20.0).
+    DeleteMessageResponse,
+    ReportResponse,
     # WS1 — star response types (0.16.0).
     MessageStarResponse,
     ThreadStarResponse,
@@ -62,6 +70,9 @@ from .types import (
     EnableLinkScanningResponse,
     EnableLinkScanningDisclosure,
     AgentSafetyContext,
+    # Governed Email-Effect Contract v1 (Track 2).
+    EmailEffect,
+    EffectStatus,
     MessageReceivedSafetySignal,
     MessageReceivedWebhookPayload,
     # PR 6 — HITL review queue webhook payload types.
@@ -81,9 +92,12 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.18.0"
+__version__ = "0.21.0"
 
 __all__ = [
+    # Message delete response (0.20.0).
+    "DeleteMessageResponse",
+    "ReportResponse",
     # WS1 — star response types (0.16.0).
     "MessageStarResponse",
     "ThreadStarResponse",
@@ -105,6 +119,13 @@ __all__ = [
     # Migration 040 — scheduled-send.
     "SchedulingError",
     "TimezoneRequiredError",
+    # Governed Email-Effect Contract v1 (Track 2).
+    "EmailEffectError",
+    "EmailEffectRejectedError",
+    "EmailEffectHeldError",
+    "EmailEffectRetryableError",
+    "EmailEffect",
+    "EffectStatus",
     "WebhookSummary",
     "WebhookDeliverySummary",
     "WebhookDeliveryStatus",

{replylayer-0.18.0 → replylayer-0.21.0}/replylayer/_client.py

@@ -36,6 +36,7 @@ class ReplyLayer:
         timeout: float = 30.0,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         if not api_key:
             raise ReplyLayerError(
@@ -43,6 +44,12 @@ class ReplyLayer:
                 "api_key is required. Get yours at https://app.replylayer.ai/connect",
             )
 
+        # Governed Email-Effect Contract v1 (Track 2) — client-default for the
+        # `Prefer: outcome=strict` opt-in. When True, messages.send / .reply
+        # request a non-2xx (503/422/409) for a held/blocked outcome, raising the
+        # matching EmailEffectError subclass instead of resolving a 200. Default
+        # False is byte-identical to today (200 with `email_effect` in the body,
+        # no throw). Override per-call via `messages.send(strict_outcome=...)`.
         self._http = SyncHttpClient(
             api_key=api_key,
             base_url=base_url.rstrip("/"),
@@ -50,6 +57,7 @@ class ReplyLayer:
             timeout=timeout,
             max_retry_after_seconds=max_retry_after_seconds,
             on_retry=on_retry,
+            strict_outcome=strict_outcome,
         )
 
         self.domains = SyncDomains(self._http)
@@ -87,6 +95,7 @@ class AsyncReplyLayer:
         timeout: float = 30.0,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         if not api_key:
             raise ReplyLayerError(
@@ -94,6 +103,7 @@ class AsyncReplyLayer:
                 "api_key is required. Get yours at https://app.replylayer.ai/connect",
             )
 
+        # Governed Email-Effect Contract v1 (Track 2) — see ReplyLayer above.
         self._http = AsyncHttpClient(
             api_key=api_key,
             base_url=base_url.rstrip("/"),
@@ -101,6 +111,7 @@ class AsyncReplyLayer:
             timeout=timeout,
             max_retry_after_seconds=max_retry_after_seconds,
             on_retry=on_retry,
+            strict_outcome=strict_outcome,
         )
 
         self.domains = AsyncDomains(self._http)

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

@@ -9,7 +9,7 @@ import httpx
 
 from .errors import ReplyLayerError, error_from_response
 
-_VERSION = "0.18.0"
+_VERSION = "0.21.0"
 _USER_AGENT = f"replylayer-sdk-py/{_VERSION}"
 _PROTECTED_HEADER_KEYS = frozenset({"authorization", "content-type", "user-agent"})
 
@@ -47,6 +47,7 @@ class SyncHttpClient:
         timeout: float,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         self._api_key = api_key
         self._base_url = base_url
@@ -54,6 +55,10 @@ class SyncHttpClient:
         self._timeout = timeout
         self._max_retry_after_seconds = max_retry_after_seconds
         self._on_retry = on_retry
+        # Governed Email-Effect Contract v1 (Track 2) — client default for the
+        # `Prefer: outcome=strict` opt-in. Read by SyncMessages/AsyncMessages
+        # send/reply as the fallback when the per-call `strict_outcome` is None.
+        self._strict_outcome = strict_outcome
         self._client = httpx.Client(timeout=timeout)
 
     def close(self) -> None:
@@ -194,6 +199,7 @@ class AsyncHttpClient:
         timeout: float,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         self._api_key = api_key
         self._base_url = base_url
@@ -201,6 +207,8 @@ class AsyncHttpClient:
         self._timeout = timeout
         self._max_retry_after_seconds = max_retry_after_seconds
         self._on_retry = on_retry
+        # Governed Email-Effect Contract v1 (Track 2) — see SyncHttpClient.
+        self._strict_outcome = strict_outcome
         self._client = httpx.AsyncClient(timeout=timeout)
 
     async def aclose(self) -> None:

{replylayer-0.18.0 → replylayer-0.21.0}/replylayer/errors.py

@@ -113,6 +113,92 @@ class TimezoneRequiredError(SchedulingError):
         )
 
 
+# Governed Email-Effect Contract v1 (Track 2) — strict-outcome opt-in errors.
+#
+# Raised ONLY when the caller opted in via `strict_outcome=True`
+# (Prefer: outcome=strict) AND the server maps a non-delivered terminal/held
+# outcome to a non-2xx. The error body carries the full governed payload
+# (`message_id`, `status`, `scan`, `hold_context`, `email_effect`) in
+# `details`, so a caller can branch retry-vs-edit-vs-escalate from the throw.
+#
+# Default (no `strict_outcome`) is byte-identical to today: the send/reply path
+# returns HTTP 200 with `email_effect` in the body and NONE of these is raised.
+#
+# Subclass of ReplyLayerError so generic catches still work; isinstance
+# EmailEffectError narrows to the strict-outcome family. Status-code → subclass:
+#   503 EMAIL_EFFECT_HELD_INFRA → EmailEffectRetryableError (carries retry_after)
+#   422 EMAIL_EFFECT_REJECTED   → EmailEffectRejectedError  (terminal content block)
+#   409 EMAIL_EFFECT_HELD       → EmailEffectHeldError      (releasable hold)
+# The factory recognizes the family by the body carrying `details.email_effect`
+# (mirroring the TS SDK), not by the `code` string.
+
+
+class EmailEffectError(ReplyLayerError):
+    """Base for the strict-outcome (``Prefer: outcome=strict``) error family.
+
+    ``email_effect`` is the parsed ``details.email_effect`` block (the governed
+    discriminator + booleans); ``scan`` is the parsed ``details.scan`` summary.
+    Both may be None if the server omitted them.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(status_code, code, message, details)
+        d = details or {}
+        self.email_effect: dict[str, Any] | None = d.get("email_effect")
+        self.scan: dict[str, Any] | None = d.get("scan")
+
+
+class EmailEffectRejectedError(EmailEffectError):
+    """422 EMAIL_EFFECT_REJECTED — a genuine terminal content rejection.
+
+    ``email_effect.effect_status == 'blocked'`` (terminal=True). The agent's
+    correct action is edit-and-resend or escalate — NEVER retry the same body.
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(422, code, message, details)
+
+
+class EmailEffectHeldError(EmailEffectError):
+    """409 EMAIL_EFFECT_HELD — accepted into governance, releasable.
+
+    ``email_effect.effect_status == 'held_for_review'`` (releasable=True). The
+    send was quarantined / queued for human review — report "awaiting approval",
+    do not treat as a content error to fix by editing.
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(409, code, message, details)
+
+
+class EmailEffectRetryableError(EmailEffectError):
+    """503 EMAIL_EFFECT_HELD_INFRA — a transient infrastructure hold.
+
+    ``email_effect.effect_status == 'held_infrastructure'`` (retryable=True): an
+    ``inference_error`` with NO genuine model judgment, so the content was never
+    judged. The agent's correct action is retry-later (back off on repeated
+    503s). ``retry_after`` mirrors the ``Retry-After`` header (None on absent /
+    non-numeric), reusing the same null-on-NaN parse as RateLimitError.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        headers: dict[str, str],
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(503, code, message, details)
+        ra = headers.get("retry-after")
+        self.retry_after: int | None = int(ra) if ra and ra.isdigit() else None
+
+
 def error_from_response(
     status: int,
     body: dict[str, Any],
@@ -139,6 +225,24 @@ def error_from_response(
     if code in _SCHEDULING_REASON_CODES:
         return SchedulingError(status, code, message, details)
 
+    # Governed Email-Effect Contract v1 (Track 2) — strict-outcome opt-in.
+    # Precedence-first BEFORE the generic status switch so a 503 becomes an
+    # EmailEffectRetryableError (not a generic ReplyLayerError), a 422 an
+    # EmailEffectRejectedError (not a plain ValidationError), and a 409 an
+    # EmailEffectHeldError — so `isinstance(err, EmailEffectError)` works
+    # uniformly across statuses. Gated on the body carrying `email_effect`
+    # (present ONLY when the request opted in AND the server applied the strict
+    # mapping), mirroring the TS SDK's `details?.email_effect` gate — robust to
+    # the exact `code` string. Any other status falls through to the generic
+    # switch unchanged.
+    if isinstance(details, dict) and details.get("email_effect") is not None:
+        if status == 422:
+            return EmailEffectRejectedError(code, message, details)
+        if status == 409:
+            return EmailEffectHeldError(code, message, details)
+        if status == 503:
+            return EmailEffectRetryableError(code, message, headers, details)
+
     if status == 401:
         return AuthenticationError(code, message, details)
     if status == 403:

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

@@ -6,7 +6,7 @@ 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
+from ..types import DeleteMessageResponse, MessageStarResponse, Page, ReportResponse
 
 DEFAULT_LIMIT = 50
 
@@ -68,6 +68,26 @@ def _classify_idempotency_probe_error(
     return None
 
 
+def _send_extra_headers(
+    *,
+    idempotency_key: str | None,
+    strict_outcome: bool,
+) -> dict[str, str] | None:
+    """Build the per-call header dict for send/reply (Governed Email-Effect
+    Contract v1, Track 2). Adds ``Idempotency-Key`` (Track 1) and, when
+    ``strict_outcome`` resolved True, ``Prefer: outcome=strict`` — which opts
+    the request into the 503/422/409 strict mapping. ``Prefer`` is not a
+    protected header, so it threads through the existing ``extra_headers`` path.
+    Returns ``None`` when neither header applies (no behavior change).
+    """
+    headers: dict[str, str] = {}
+    if idempotency_key is not None:
+        headers["Idempotency-Key"] = idempotency_key
+    if strict_outcome:
+        headers["Prefer"] = "outcome=strict"
+    return headers or None
+
+
 class SyncMessages:
     def __init__(self, http: SyncHttpClient) -> None:
         self._http = http
@@ -85,6 +105,7 @@ class SyncMessages:
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
         idempotency_key: str | None = None,
+        strict_outcome: bool | None = None,
     ) -> dict[str, Any]:
         """Send an outbound message.
 
@@ -97,6 +118,15 @@ class SyncMessages:
             to a thread participant is admitted past an ``allowlist`` mailbox
             via the thread-scoped bypass.
 
+        ``strict_outcome`` (Governed Email-Effect Contract v1, Track 2) opts the
+        request into ``Prefer: outcome=strict``: a held/blocked outcome then
+        returns a non-2xx (503 infra-hold / 422 content-block / 409 releasable-
+        hold) and the SDK raises the matching :class:`EmailEffectError` subclass
+        carrying ``email_effect`` + ``scan`` from ``details``, instead of
+        resolving a 200 with the outcome hidden in ``status``. ``None`` (default)
+        inherits the client-level ``strict_outcome``; ``False`` forces today's
+        200 behavior for this call.
+
         ``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``
@@ -132,9 +162,12 @@ class SyncMessages:
             payload["subaddress_mode"] = subaddress_mode
         if attachment_ids is not None:
             payload["attachment_ids"] = attachment_ids
-        extra_headers: dict[str, str] | None = None
-        if idempotency_key is not None:
-            extra_headers = {"Idempotency-Key": idempotency_key}
+        effective_strict = (
+            strict_outcome if strict_outcome is not None else self._http._strict_outcome
+        )
+        extra_headers = _send_extra_headers(
+            idempotency_key=idempotency_key, strict_outcome=effective_strict
+        )
         return self._http.request(
             "POST", "/v1/messages/send", body=payload, extra_headers=extra_headers
         )
@@ -209,6 +242,7 @@ class SyncMessages:
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
         idempotency_key: str | None = None,
+        strict_outcome: bool | None = None,
     ) -> dict[str, Any]:
         """Reply to an inbound message.
 
@@ -216,6 +250,10 @@ class SyncMessages:
         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`.
+
+        ``strict_outcome`` (Governed Email-Effect Contract v1, Track 2) opts the
+        request into ``Prefer: outcome=strict`` — see :meth:`send`. ``None``
+        inherits the client-level default; ``False`` forces the 200 path.
         """
         payload: dict[str, Any] = {"body": body}
         if html is not None:
@@ -226,9 +264,12 @@ class SyncMessages:
             payload["subaddress_mode"] = subaddress_mode
         if attachment_ids is not None:
             payload["attachment_ids"] = attachment_ids
-        extra_headers: dict[str, str] | None = None
-        if idempotency_key is not None:
-            extra_headers = {"Idempotency-Key": idempotency_key}
+        effective_strict = (
+            strict_outcome if strict_outcome is not None else self._http._strict_outcome
+        )
+        extra_headers = _send_extra_headers(
+            idempotency_key=idempotency_key, strict_outcome=effective_strict
+        )
         return self._http.request(
             "POST",
             f"/v1/messages/{message_id}/reply",
@@ -296,6 +337,40 @@ class SyncMessages:
             body["reason"] = reason
         return self._http.request("POST", f"/v1/messages/{message_id}/block", body=body)
 
+    def report(self, message_id: str, *, reason: str | None = None) -> "ReportResponse":
+        """Atomic report-and-block for an INBOUND message.
+
+        Blocks a held message and adds the resolved sender to the account-wide
+        inbound blocklist (idempotent); optional reason is persisted to audit.
+        An outbound target raises ``ReplyLayerError`` (422
+        REPORT_OUTBOUND_UNSUPPORTED) — an outbound message has no inbound sender
+        to block.
+        """
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return self._http.request("POST", f"/v1/messages/{message_id}/report", body=body)
+
+    def delete(self, message_id: str) -> "DeleteMessageResponse":
+        """Soft-delete a message and purge its raw MIME from object storage.
+
+        Direction-agnostic — works on inbound or outbound rows in a deletable
+        state (e.g. available / quarantined / delivered / bounced); draft /
+        scheduled / dispatching rows return 409. Idempotent: re-deleting an
+        already-deleted row returns 200 again.
+
+        Auth: admin keys and session cookies always; mailbox-bound agent keys
+        only when the account has agent message-deletion enabled — otherwise a
+        403 MESSAGE_DELETE_NOT_PERMITTED raises ``ForbiddenError`` carrying the
+        machine-readable denial envelope in ``.details`` (reason_axis /
+        remedy / cheapest_next_step / upgrade_url). 404 raises ``NotFoundError``
+        when not found or not visible; 409 ``ReplyLayerError`` on a
+        non-deletable state or an active legal hold.
+
+        Bodyless DELETE — no request body is sent.
+        """
+        return self._http.request("DELETE", f"/v1/messages/{message_id}")
+
     def firewall_release(self, message_id: str) -> dict[str, Any]:
         """Migration 047 — release a state='firewall_blocked' message.
 
@@ -391,6 +466,7 @@ class AsyncMessages:
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
         idempotency_key: str | None = None,
+        strict_outcome: bool | None = None,
     ) -> dict[str, Any]:
         """Send an outbound message.
 
@@ -405,6 +481,12 @@ class AsyncMessages:
         message instead of re-sending. The key travels in the ``Idempotency-Key``
         request header. See :meth:`get_idempotency_replay`.
 
+        ``strict_outcome`` (Governed Email-Effect Contract v1, Track 2) opts the
+        request into ``Prefer: outcome=strict`` — a held/blocked outcome returns
+        a non-2xx (503/422/409) raising the matching :class:`EmailEffectError`
+        subclass. See :meth:`SyncMessages.send`. ``None`` inherits the
+        client-level default; ``False`` forces the 200 path.
+
         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``
@@ -429,9 +511,12 @@ class AsyncMessages:
             payload["subaddress_mode"] = subaddress_mode
         if attachment_ids is not None:
             payload["attachment_ids"] = attachment_ids
-        extra_headers: dict[str, str] | None = None
-        if idempotency_key is not None:
-            extra_headers = {"Idempotency-Key": idempotency_key}
+        effective_strict = (
+            strict_outcome if strict_outcome is not None else self._http._strict_outcome
+        )
+        extra_headers = _send_extra_headers(
+            idempotency_key=idempotency_key, strict_outcome=effective_strict
+        )
         return await self._http.request(
             "POST", "/v1/messages/send", body=payload, extra_headers=extra_headers
         )
@@ -507,11 +592,16 @@ class AsyncMessages:
         subaddress_mode: str | None = None,
         attachment_ids: list[str] | None = None,
         idempotency_key: str | None = None,
+        strict_outcome: bool | 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`.
+
+        ``strict_outcome`` (Governed Email-Effect Contract v1, Track 2) opts the
+        request into ``Prefer: outcome=strict`` — see :meth:`SyncMessages.send`.
+        ``None`` inherits the client-level default; ``False`` forces the 200 path.
         """
         payload: dict[str, Any] = {"body": body}
         if html is not None:
@@ -522,9 +612,12 @@ class AsyncMessages:
             payload["subaddress_mode"] = subaddress_mode
         if attachment_ids is not None:
             payload["attachment_ids"] = attachment_ids
-        extra_headers: dict[str, str] | None = None
-        if idempotency_key is not None:
-            extra_headers = {"Idempotency-Key": idempotency_key}
+        effective_strict = (
+            strict_outcome if strict_outcome is not None else self._http._strict_outcome
+        )
+        extra_headers = _send_extra_headers(
+            idempotency_key=idempotency_key, strict_outcome=effective_strict
+        )
         return await self._http.request(
             "POST",
             f"/v1/messages/{message_id}/reply",
@@ -584,6 +677,17 @@ class AsyncMessages:
             body["reason"] = reason
         return await self._http.request("POST", f"/v1/messages/{message_id}/block", body=body)
 
+    async def report(self, message_id: str, *, reason: str | None = None) -> "ReportResponse":
+        """Atomic report-and-block for an INBOUND message (async). See SyncMessages.report."""
+        body: dict[str, Any] = {}
+        if reason is not None:
+            body["reason"] = reason
+        return await self._http.request("POST", f"/v1/messages/{message_id}/report", body=body)
+
+    async def delete(self, message_id: str) -> "DeleteMessageResponse":
+        """Soft-delete a message and purge its raw MIME (async). See SyncMessages.delete."""
+        return await self._http.request("DELETE", f"/v1/messages/{message_id}")
+
     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(

{replylayer-0.18.0 → replylayer-0.21.0}/replylayer/types.py

@@ -590,6 +590,46 @@ class HoldContext(TypedDict):
     summary_reasons: list[str]
 
 
+EffectStatus = Literal["sent", "held_for_review", "held_infrastructure", "blocked"]
+
+
+class EmailEffect(TypedDict):
+    """Governed Email-Effect Contract v1 (Track 2) — the thin derived VIEW that
+    lets an agent branch retry-vs-edit-vs-escalate-vs-release in one read,
+    instead of walking ``status -> scan.verdict -> hold_context ->
+    findings[].failure_class``.
+
+    Outbound-only: present on send/reply success bodies (and on the opt-in
+    strict 4xx/5xx error body's ``details``), and on outbound message reads
+    (``GET /v1/messages/:id`` + thread-detail items). Inbound rows carry
+    ``agent_safety_context`` instead and never carry ``email_effect``; a
+    never-sent compose draft / pre-dispatch transient read OMITS the field
+    entirely (the server returns no ``email_effect`` key).
+
+    ``effect_status`` discriminates the four outcome classes:
+      * ``sent``               — dispatched (or in-flight/optimistic), not held.
+      * ``held_for_review``    — quarantine / pending_review (content or HITL);
+                                 releasable=True, terminal=False.
+      * ``held_infrastructure``— a transient ``inference_error`` infra hold with
+                                 NO genuine model-judgment block/quarantine;
+                                 retryable=True, terminal=False (retry-later).
+      * ``blocked``            — a genuine terminal content rejection;
+                                 terminal=True, releasable=False (edit/escalate).
+
+    Open enum: tolerant readers MUST treat an unknown ``effect_status``
+    fail-closed (never as ``sent``).
+    """
+    effect_status: EffectStatus
+    # True iff the row is human-releasable (status in {quarantined, pending_review}).
+    releasable: bool
+    # True iff the outcome is terminal (status in {blocked, delivered, bounced}).
+    terminal: bool
+    # True iff this is a transient infra hold (inference_error, no genuine
+    # model judgment) OR an indeterminate keyed-dispatch — the agent's correct
+    # action is retry-later, never edit-content.
+    retryable: bool
+
+
 class SendMessageResponse(TypedDict):
     message_id: str
     status: Literal["sent", "quarantined", "blocked", "pending_review"]
@@ -598,6 +638,10 @@ class SendMessageResponse(TypedDict):
     scan: NotRequired["ScanSummary | None"]
     # Policy/HITL hold reason; null when scan explains the hold or status='sent'.
     hold_context: NotRequired["HoldContext | None"]
+    # Governed Email-Effect Contract v1 (Track 2). Outbound-only derived VIEW —
+    # present on send/reply success bodies; OMITTED (key absent) on a never-sent
+    # compose draft. Carried in the strict-mode 4xx/5xx error body's `details`.
+    email_effect: NotRequired["EmailEffect | None"]
     daily_limit: int
     sends_remaining: int
     # Outbound HTML sanitization (Phase 2, D3). Additive — populated ONLY on the
@@ -973,6 +1017,10 @@ class GetMessageResponse(TypedDict, total=False):
     attachments: Required[list[MessageAttachment]]
     scan: Required[ScanSummary | None]
     agent_safety_context: NotRequired["AgentSafetyContext | None"]
+    # Governed Email-Effect Contract v1 (Track 2). Outbound-only derived VIEW;
+    # OMITTED (key absent) on inbound rows (which carry agent_safety_context) and
+    # on never-sent / pre-dispatch-transient outbound rows.
+    email_effect: NotRequired["EmailEffect | None"]
     thread_id: Required[str | None]
     in_reply_to: Required[str | None]
     # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
@@ -1159,6 +1207,24 @@ class BlockResponse(TypedDict):
     message_id: str
 
 
+class ReportResponse(TypedDict):
+    message_id: str
+    state: str
+    blocked: bool
+    already_blocked: bool
+    sender_blocklisted: str | None
+    already_blocklisted: bool
+    pattern_type: str | None
+
+
+class DeleteMessageResponse(TypedDict):
+    status: Literal["deleted"]
+    message_id: str
+    raw_mime_deleted: bool
+    derivatives_tombstoned: int
+    r2_objects_failed: list[str]
+
+
 # === Drafts ===
 #
 # A draft is a message in state='draft'. Scanner runs at create + update and
@@ -1279,6 +1345,13 @@ class ThreadSummary(TypedDict):
     # Required — mirrors TS SDK ThreadSummary.starred (required, not optional).
     starred: bool
     participants: list[str]
+    # Inbox redesign §6.2 — additive/optional row enrichment (absent from an
+    # older API). scan: worst-across-thread summary with held delivery states
+    # folded in; body_preview: latest-message PII-redacted snippet;
+    # has_attachment: any member message has an attachment.
+    scan: NotRequired["ScanSummary | None"]
+    body_preview: NotRequired[str | None]
+    has_attachment: NotRequired[bool]
 
 
 class GetThreadResponse(TypedDict):

{replylayer-0.18.0 → replylayer-0.21.0}/tests/test_async.py

@@ -159,6 +159,44 @@ async def test_async_domains_recheck():
     await rl.aclose()
 
 
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_messages_report():
+    respx.post(f"{BASE}/v1/messages/msg1/report").mock(
+        return_value=httpx.Response(200, json={
+            "message_id": "msg1", "state": "blocked", "blocked": True, "already_blocked": False,
+            "sender_blocklisted": "x@evil.test", "already_blocklisted": False, "pattern_type": "email",
+        })
+    )
+    rl = async_sdk()
+    res = await rl.messages.report("msg1")
+    assert res["blocked"] is True
+    assert res["sender_blocklisted"] == "x@evil.test"
+    await rl.aclose()
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_messages_delete():
+    respx.delete(f"{BASE}/v1/messages/msg1").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "status": "deleted",
+                "message_id": "msg1",
+                "raw_mime_deleted": True,
+                "derivatives_tombstoned": 0,
+                "r2_objects_failed": [],
+            },
+        )
+    )
+    rl = async_sdk()
+    res = await rl.messages.delete("msg1")
+    assert res["status"] == "deleted"
+    assert res["raw_mime_deleted"] is True
+    await rl.aclose()
+
+
 @respx.mock
 @pytest.mark.asyncio
 async def test_async_mailboxes_create():

replylayer-0.21.0/tests/test_governed_email_effect.py

@@ -0,0 +1,399 @@
+"""
+Python SDK Track 2 — Governed Email-Effect Contract v1 tests.
+
+Covers:
+  * The ``strict_outcome`` opt-in header (``Prefer: outcome=strict``) — per-call,
+    client-default, ``None`` inherit, and ``False`` per-call override — on
+    send / reply, sync + async (parity with the Idempotency-Key forwarding tests).
+  * The strict-mode typed error family: 503 → EmailEffectRetryableError (with
+    retry_after parse), 422 → EmailEffectRejectedError, 409 → EmailEffectHeldError,
+    plus email_effect / scan extraction from details and the EmailEffectError
+    base catch.
+  * The ``email_effect`` body field riding through on the default (200) path.
+  * EffectStatus enum members frozen (the TS↔Python contract sweep anchor).
+
+Mirrors the respx mock style of test_messages_idempotency.py.
+"""
+import typing
+
+import httpx
+import pytest
+import respx
+
+from replylayer import (
+    AsyncReplyLayer,
+    EffectStatus,
+    EmailEffect,
+    EmailEffectError,
+    EmailEffectHeldError,
+    EmailEffectRejectedError,
+    EmailEffectRetryableError,
+    ReplyLayer,
+    ReplyLayerError,
+)
+
+BASE = "https://api.test.replylayer.ai"
+
+
+def sdk(*, strict_outcome: bool = False) -> ReplyLayer:
+    return ReplyLayer(
+        api_key="rl_live_test", base_url=BASE, max_retries=0, strict_outcome=strict_outcome
+    )
+
+
+def async_sdk(*, strict_outcome: bool = False) -> AsyncReplyLayer:
+    return AsyncReplyLayer(
+        api_key="rl_live_test", base_url=BASE, max_retries=0, strict_outcome=strict_outcome
+    )
+
+
+def _sent_fixture() -> dict:
+    return {
+        "message_id": "msg1",
+        "status": "sent",
+        "daily_limit": 15,
+        "sends_remaining": 14,
+        "email_effect": {
+            "effect_status": "sent",
+            "releasable": False,
+            "terminal": False,
+            "retryable": False,
+        },
+    }
+
+
+def _strict_error_body(code: str, effect_status: str, *, releasable: bool, terminal: bool, retryable: bool) -> dict:
+    return {
+        "error": "outcome held by governance",
+        "code": code,
+        "details": {
+            "message_id": "msg1",
+            "status": "blocked" if effect_status == "blocked" else "quarantined",
+            "scan": {"verdict": "blocked", "categories": [], "findings": []},
+            "email_effect": {
+                "effect_status": effect_status,
+                "releasable": releasable,
+                "terminal": terminal,
+                "retryable": retryable,
+            },
+        },
+    }
+
+
+# --------------------------------------------------------------------------
+# Header forwarding — Prefer: outcome=strict.
+# --------------------------------------------------------------------------
+
+
+@respx.mock
+def test_send_per_call_strict_forwards_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk().messages.send(
+        from_mailbox="support", to="u@example.com", subject="Hi", body="Hello", strict_outcome=True
+    )
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+@respx.mock
+def test_send_default_omits_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk().messages.send(from_mailbox="support", to="u@example.com", subject="Hi", body="Hello")
+    assert route.calls.last.request.headers.get("Prefer") is None
+
+
+@respx.mock
+def test_send_client_default_strict_forwards_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk(strict_outcome=True).messages.send(
+        from_mailbox="support", to="u@example.com", subject="Hi", body="Hello"
+    )
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+@respx.mock
+def test_send_per_call_false_overrides_client_default():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk(strict_outcome=True).messages.send(
+        from_mailbox="support", to="u@example.com", subject="Hi", body="Hello", strict_outcome=False
+    )
+    assert route.calls.last.request.headers.get("Prefer") is None
+
+
+@respx.mock
+def test_send_none_inherits_client_default():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    # strict_outcome left at its None default → inherits the client-level True.
+    sdk(strict_outcome=True).messages.send(
+        from_mailbox="support", to="u@example.com", subject="Hi", body="Hello"
+    )
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+@respx.mock
+def test_reply_per_call_strict_forwards_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/orig1/reply").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk().messages.reply("orig1", body="Thanks", strict_outcome=True)
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+@respx.mock
+def test_strict_coexists_with_idempotency_key():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    sdk().messages.send(
+        from_mailbox="support",
+        to="u@example.com",
+        subject="Hi",
+        body="Hello",
+        idempotency_key="k1",
+        strict_outcome=True,
+    )
+    req = route.calls.last.request
+    assert req.headers.get("Prefer") == "outcome=strict"
+    assert req.headers.get("Idempotency-Key") == "k1"
+
+
+@respx.mock
+async def test_async_send_client_default_strict_forwards_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    await async_sdk(strict_outcome=True).messages.send(
+        from_mailbox="support", to="u@example.com", subject="Hi", body="Hello"
+    )
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+@respx.mock
+async def test_async_reply_per_call_strict_forwards_prefer_header():
+    route = respx.post(f"{BASE}/v1/messages/orig1/reply").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    await async_sdk().messages.reply("orig1", body="Thanks", strict_outcome=True)
+    assert route.calls.last.request.headers.get("Prefer") == "outcome=strict"
+
+
+# --------------------------------------------------------------------------
+# Strict-mode typed errors.
+# --------------------------------------------------------------------------
+
+
+@respx.mock
+def test_strict_422_raises_rejected_error_with_effect():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            422,
+            json=_strict_error_body(
+                "EMAIL_EFFECT_REJECTED", "blocked", releasable=False, terminal=True, retryable=False
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRejectedError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    err = ei.value
+    assert isinstance(err, EmailEffectError)
+    assert err.status_code == 422
+    assert err.code == "EMAIL_EFFECT_REJECTED"
+    assert err.email_effect is not None
+    assert err.email_effect["effect_status"] == "blocked"
+    assert err.email_effect["terminal"] is True
+    assert err.scan is not None
+    assert err.scan["verdict"] == "blocked"
+
+
+@respx.mock
+def test_strict_409_raises_held_error():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            409,
+            json=_strict_error_body(
+                "EMAIL_EFFECT_HELD", "held_for_review", releasable=True, terminal=False, retryable=False
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectHeldError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    err = ei.value
+    assert isinstance(err, EmailEffectError)
+    assert err.status_code == 409
+    assert err.email_effect["releasable"] is True
+
+
+@respx.mock
+def test_strict_503_raises_retryable_error_with_retry_after():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            503,
+            headers={"Retry-After": "30"},
+            json=_strict_error_body(
+                "EMAIL_EFFECT_HELD_INFRA",
+                "held_infrastructure",
+                releasable=False,
+                terminal=False,
+                retryable=True,
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRetryableError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    err = ei.value
+    assert isinstance(err, EmailEffectError)
+    assert err.status_code == 503
+    assert err.retry_after == 30
+    assert err.email_effect["retryable"] is True
+
+
+@respx.mock
+def test_strict_503_missing_retry_after_is_none():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            503,
+            json=_strict_error_body(
+                "EMAIL_EFFECT_HELD_INFRA",
+                "held_infrastructure",
+                releasable=False,
+                terminal=False,
+                retryable=True,
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRetryableError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    assert ei.value.retry_after is None
+
+
+@respx.mock
+def test_strict_503_nonnumeric_retry_after_is_none():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            503,
+            headers={"Retry-After": "Wed, 21 Oct 2026 07:28:00 GMT"},
+            json=_strict_error_body(
+                "EMAIL_EFFECT_HELD_INFRA",
+                "held_infrastructure",
+                releasable=False,
+                terminal=False,
+                retryable=True,
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRetryableError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    assert ei.value.retry_after is None
+
+
+@respx.mock
+def test_strict_reply_422_raises_rejected_error():
+    respx.post(f"{BASE}/v1/messages/orig1/reply").mock(
+        return_value=httpx.Response(
+            422,
+            json=_strict_error_body(
+                "EMAIL_EFFECT_REJECTED", "blocked", releasable=False, terminal=True, retryable=False
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRejectedError):
+        sdk().messages.reply("orig1", body="x", strict_outcome=True)
+
+
+@respx.mock
+def test_non_effect_422_stays_validation_error():
+    """A 422 WITHOUT an email-effect code must NOT become an EmailEffectError —
+    it stays the generic ValidationError path (no false-positive remap)."""
+    from replylayer import ValidationError
+
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(422, json={"error": "bad", "code": "VALIDATION_ERROR"})
+    )
+    with pytest.raises(ValidationError) as ei:
+        sdk().messages.send(from_mailbox="s", to="u@example.com", subject="Hi", body="x")
+    assert not isinstance(ei.value, EmailEffectError)
+
+
+@respx.mock
+def test_strict_422_with_email_effect_but_other_code_still_remaps():
+    """The remap is gated on the body carrying `email_effect`, not the exact
+    `code` string (parity with the TS `details?.email_effect` gate). A 422 that
+    carries email_effect still becomes an EmailEffectRejectedError."""
+    body = _strict_error_body(
+        "SOME_FUTURE_CODE", "blocked", releasable=False, terminal=True, retryable=False
+    )
+    respx.post(f"{BASE}/v1/messages/send").mock(return_value=httpx.Response(422, json=body))
+    with pytest.raises(EmailEffectRejectedError) as ei:
+        sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+    assert ei.value.code == "SOME_FUTURE_CODE"
+    assert ei.value.email_effect["effect_status"] == "blocked"
+
+
+@respx.mock
+async def test_async_strict_422_raises_rejected_error():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(
+            422,
+            json=_strict_error_body(
+                "EMAIL_EFFECT_REJECTED", "blocked", releasable=False, terminal=True, retryable=False
+            ),
+        )
+    )
+    with pytest.raises(EmailEffectRejectedError):
+        await async_sdk().messages.send(
+            from_mailbox="s", to="u@example.com", subject="Hi", body="x", strict_outcome=True
+        )
+
+
+# --------------------------------------------------------------------------
+# Default (200) path carries email_effect in the body.
+# --------------------------------------------------------------------------
+
+
+@respx.mock
+def test_default_200_body_carries_email_effect():
+    respx.post(f"{BASE}/v1/messages/send").mock(
+        return_value=httpx.Response(200, json=_sent_fixture())
+    )
+    res = sdk().messages.send(from_mailbox="s", to="u@example.com", subject="Hi", body="x")
+    assert res["email_effect"]["effect_status"] == "sent"
+    assert res["email_effect"]["terminal"] is False
+
+
+# --------------------------------------------------------------------------
+# Contract sweep anchor — EffectStatus enum members frozen.
+# --------------------------------------------------------------------------
+
+
+def test_effect_status_enum_members_frozen():
+    """TS↔Python contract: EffectStatus literal members must match the four the
+    server emits. New members are additive (open enum) — this guards against an
+    accidental DROP / typo, not against a future ADD."""
+    members = set(typing.get_args(EffectStatus))
+    assert members == {"sent", "held_for_review", "held_infrastructure", "blocked"}
+
+
+def test_email_effect_is_typeddict_with_expected_keys():
+    keys = set(EmailEffect.__annotations__.keys())
+    assert keys == {"effect_status", "releasable", "terminal", "retryable"}

{replylayer-0.18.0 → replylayer-0.21.0}/tests/test_resources.py

@@ -314,6 +314,58 @@ def test_messages_block():
     assert res["status"] == "blocked"
 
 
+@respx.mock
+def test_messages_report():
+    respx.post(f"{BASE}/v1/messages/msg1/report").mock(return_value=httpx.Response(200, json={
+        "message_id": "msg1", "state": "blocked", "blocked": True, "already_blocked": False,
+        "sender_blocklisted": "spammer@evil.test", "already_blocklisted": False, "pattern_type": "email",
+    }))
+    res = sdk().messages.report("msg1", reason="spam")
+    assert res["blocked"] is True
+    assert res["sender_blocklisted"] == "spammer@evil.test"
+    assert res["pattern_type"] == "email"
+
+
+@respx.mock
+def test_messages_delete():
+    respx.delete(f"{BASE}/v1/messages/msg1").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "status": "deleted",
+                "message_id": "msg1",
+                "raw_mime_deleted": True,
+                "derivatives_tombstoned": 2,
+                "r2_objects_failed": [],
+            },
+        )
+    )
+    res = sdk().messages.delete("msg1")
+    assert res["status"] == "deleted"
+    assert res["raw_mime_deleted"] is True
+    assert res["derivatives_tombstoned"] == 2
+    assert res["r2_objects_failed"] == []
+
+
+@respx.mock
+def test_messages_delete_403_raises_forbidden():
+    respx.delete(f"{BASE}/v1/messages/msg1").mock(
+        return_value=httpx.Response(
+            403,
+            json={
+                "error": "Agent keys are not permitted to delete messages on this account.",
+                "code": "MESSAGE_DELETE_NOT_PERMITTED",
+                "details": {"reason_axis": "account_policy", "remedy": "enable_account_policy"},
+            },
+        )
+    )
+    with pytest.raises(ForbiddenError) as exc:
+        sdk().messages.delete("msg1")
+    assert exc.value.code == "MESSAGE_DELETE_NOT_PERMITTED"
+    assert exc.value.details is not None
+    assert exc.value.details["reason_axis"] == "account_policy"
+
+
 @respx.mock
 def test_messages_list_with_filters():
     respx.get(f"{BASE}/v1/mailboxes/mbx1/messages").mock(return_value=httpx.Response(200, json={"messages": []}))