replylayer 0.21.0__tar.gz → 0.22.1__tar.gz

replylayer-0.21.0/README.md → replylayer-0.22.1/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.4
+Name: replylayer
+Version: 0.22.1
+Summary: Official Python SDK for ReplyLayer — email for AI agents
+Project-URL: Homepage, https://replylayer.ai
+Project-URL: Repository, https://github.com/replylayer/rly
+Project-URL: Issues, https://github.com/replylayer/rly/issues
+License-Expression: MIT
+Keywords: agent,ai,email,mailbox,replylayer,sdk,webhook
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: cli
+Requires-Dist: rly>=0.6.3; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
 # replylayer
 
 Official Python SDK for [ReplyLayer](https://replylayer.ai) — secure email for AI agents.
@@ -80,7 +100,8 @@ contract — read it before relying on retries:
 - **`5xx` is retried only on non-mutating (`GET`) requests.** A `5xx` on a
   `POST` / `PATCH` / `DELETE` is **not** retried — the request may have executed,
   so a retry risks a double-send (or, for `DELETE`, retrying a lost-but-applied
-  delete into a confusing `404`).
+  delete into a confusing `404`). To retry a `send` / `reply` safely, pass an
+  idempotency key — see [Idempotent sends](#idempotent-sends).
 - **Multipart uploads are never retried** (a retry would re-send the body).
 - **Long `Retry-After` values block up to `max_retry_after_seconds`** (default
   ~67 minutes, sized to ride out hour-bucket rate limits for batch jobs). When a
@@ -95,21 +116,57 @@ contract — read it before relying on retries:
   may be a coroutine (it's awaited); a raising callback is swallowed so it can't
   break the retry.
 
+## Idempotent sends
+
+Because a `5xx` on a send is **not** auto-retried (a blind retry risks a second
+delivery + a second charge), the SDK gives you a way to retry it yourself
+*safely*. `messages.send`, `messages.reply`, and scheduled sends via
+`drafts.create` (with `send_at`) accept an `idempotency_key`: a network-retried
+request carrying the same key produces **at most one** message and one charge —
+the server replays the original outcome and returns the **same `message_id`**
+instead of sending again.
+
+```python
+import uuid
+
+key = str(uuid.uuid4())  # stable per send intent — persist it with the job
+
+# First call sends; a same-key retry replays the first result (no second send).
+sent = rl.messages.send(
+    from_mailbox="support",
+    to="user@example.com",
+    subject="Hi",
+    body="Hello",
+    idempotency_key=key,
+)
+print(sent["message_id"])  # a same-key retry returns this SAME id
+```
+
+The key travels as the `Idempotency-Key` request header and is permanent (no
+expiry). A non-throwing probe, `rl.messages.get_idempotency_replay(key)`, reports
+whether a key already produced a result, is still in flight, or is a miss — call
+it before a retry whose local inputs (a staged attachment, the original message)
+may no longer be available. The async client exposes the same methods.
+
 ## Resources
 
 | Resource | Methods |
 |----------|---------|
-| `rl.mailboxes` | `create`, `list`, `delete`, `update`, `set_recipient_policy` |
+| `rl.domains` | `create`, `list`, `get`, `verify`, `update_self_hosted_config`, `delete`, `set_default`, `recheck` |
+| `rl.mailboxes` | `create`, `list`, `get_mailbox`, `delete`, `update`, `set_recipient_policy`, `set_thread_replies`, `set_agent_send_containment`, `set_agent_send_policy`, `set_attachment_access`, `set_sender_policy` |
 | `rl.mailboxes.allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
-| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block`, `set_starred` |
+| `rl.mailboxes.inbound_allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
+| `rl.messages` | `send`, `list`, `get`, `reply`, `get_idempotency_replay`, `wait`, `release`, `block`, `report`, `delete`, `firewall_release`, `mark_read`, `set_starred`, `approve_review`, `deny_review` |
 | `rl.drafts` | `create`, `get`, `list`, `update`, `send`, `delete` |
-| `rl.threads` | `list`, `get`, `set_starred` |
+| `rl.threads` | `list`, `get`, `mark_read`, `set_starred` |
 | `rl.attachments` | `get_download_url`, `get_preview`, `upload`, `get_upload`, `delete_upload` |
 | `rl.webhooks` | `create`, `list`, `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `retry_delivery` |
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
-| `rl.suppressions` | `list`, `delete` |
+| `rl.suppressions` | `list`, `add`, `add_bulk`, `delete` |
+| `rl.inbound_blocklist` | `list`, `add`, `add_bulk`, `delete` |
 | `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
-| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning` |
+| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning`, `export` |
+| `rl.legal_holds` | `apply`, `release`, `list`, `get` |
 | `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.
@@ -132,7 +189,7 @@ if draft["worst_decision"] == "allow":
 
 The send/reply/draft-send response carries two additive, nullable keys that explain a held send inline (no second `messages.get` call). `result["scan"]` is the vendor-neutral scanner verdict (`ScanSummary`); `result["hold_context"]` (`{"trigger_source", "summary_reasons"}` or `None`) is the policy/HITL reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/HITL hold — a clean scan held for review by your mailbox policy, or a scanner review-flag held as quarantine on a plan without the review queue (`trigger_source`: `mailbox_policy` | `scanner` | `both`).
 
-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.)
+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 decides.** When async dispatch is available the server returns `202` with `status="queued_for_dispatch"` (`AsyncSendAck`); otherwise it ignores the hint and returns a normal `200` `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`, `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`.
@@ -236,7 +293,7 @@ rl.mailboxes.update(
 
 ### Advanced PII config (Pro+)
 
-PR 8 added `pii_redaction_config` for **per-detector** control over redaction (e.g. "leave email visible, redact everything else") and **operator-level** rendering (`partial_mask` for credit cards, `hash_replace` for emails you want to dedupe without exposing). Pro+ feature; only meaningful when `pii_mode="redacted"`.
+`pii_redaction_config` gives **per-detector** control over redaction (e.g. "leave email visible, redact everything else") and **operator-level** rendering (`partial_mask` for credit cards, `hash_replace` for emails you want to dedupe without exposing). Pro+ feature; only meaningful when `pii_mode="redacted"`.
 
 ```python
 # Per-detector toggle: show emails to the agent, keep everything else redacted.
@@ -358,7 +415,7 @@ A send/reply/draft-send to a recipient on your do-not-contact (suppression) list
 
 Allowlist mutations are admin-only — granting send permission to an LLM defeats the containment boundary. Agents *can* `list` (so they can see what they're allowed to email) but not `add`/`add_bulk`/`delete`. Three new webhook events: `recipient_allowlist.added`, `recipient_allowlist.removed`, `mailbox.recipient_policy_changed`.
 
-### Domain entries (sprint 039)
+### Domain entries
 
 Entries can be either an exact email (`alice@corp.com`) or a bare-domain pattern (`@corp.com`) that matches every address at that domain. Exact-domain only — `@corp.com` matches `*@corp.com` but NOT `eve@sub.corp.com`.
 
@@ -383,7 +440,7 @@ Responses expose `pattern_type: "email" | "domain"` on every add/list/delete/bul
 
 Blocklist precedence still holds: a domain-block beats an exact-allow at the same domain. Malformed patterns (`@`, `@.com`, `@foo`, `@corp-.com`, non-ASCII) raise `ReplyLayerError` with `.code == "INVALID_EMAIL"` (message: `"Invalid email or domain pattern"`).
 
-### Blocked attempts (migration 038)
+### Blocked attempts
 
 Every send the allowlist gate rejects writes an append-only audit row and emits a deduped `recipient_allowlist.blocked_attempt` webhook. Review the log to see what your agent tried to email and one-click add legitimate recipients.
 
@@ -426,6 +483,28 @@ if not status["active"] and status["privacy_ok"]:
 
 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(...)`).
 
+## Trusted instruction sources
+
+Every inbound message read carries `agent_safety_context` with `untrusted_content` `True` — the body is external data, not instructions for the agent to act on. Trusted instruction sources is an opt-in, **read-path-only** relaxation of that default for one specific, customer-designated, *verified* sender address per mailbox (address-grain only — there is no domain-wide grant). It does not change what a resulting send is allowed to do; the only related send-side control is a per-mailbox strict-recipient toggle, configured outside the SDK.
+
+The relaxation only applies on a read when **every** layer is satisfied, entirely on the server side: the platform feature is enabled, the mailbox's instruction-trust mode is on, the designated sender's message passed Mailgun sender verification (`verified_aligned`), the message scanned clean and is `available`, and the reading API key is a `role="agent"` key with the per-key capability enabled. There is no client-side opt-in — the SDK does not send any header or constructor flag to request this; a message either qualifies under the operator's configuration or it doesn't, and the response reflects that automatically:
+
+```python
+result = rl.messages.wait(mailbox["id"])
+msg = result["message"]
+ctx = msg.get("agent_safety_context") if msg else None
+if ctx and ctx.get("instruction_trust"):
+    # Gate passed: guidance was REPLACED with trusted-instruction wording (the
+    # agent may act on this verified sender's own explicit request in this
+    # message). untrusted_content is still True — this is metadata, not a
+    # content-safety judgment.
+    print(ctx["guidance"])
+    print(ctx["instruction_trust"])
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+```
+
+A human account owner enables the mailbox mode and the key's capability, and designates the trusted sender, from the dashboard (each a loosening change requiring session re-auth). Both the mailbox mode and the per-key capability default to off, so existing integrations are unaffected until a customer opts in. This is a read-path signal only — a copied or hijacked API key cannot self-grant the capability, and there is nothing for a client to set to request it.
+
 ## 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.
@@ -491,9 +570,9 @@ import json
 payload = json.loads(request.body)
 # payload["event"] is the discriminator — NOT payload["type"]
 if payload["event"] == "message.received":
-    # handle inbound message
+    print("handle inbound message")
 elif payload["event"] == "message.dispatch_failed":
-    # handle failed outbound send
+    print("handle failed outbound send")
 ```
 
 ## Context managers

replylayer-0.21.0/PKG-INFO → replylayer-0.22.1/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: replylayer
-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
-Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27
-Requires-Dist: typing-extensions>=4.0
-Provides-Extra: cli
-Requires-Dist: rly>=0.6.3; extra == 'cli'
-Provides-Extra: dev
-Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: respx>=0.21; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # replylayer
 
 Official Python SDK for [ReplyLayer](https://replylayer.ai) — secure email for AI agents.
@@ -97,7 +80,8 @@ contract — read it before relying on retries:
 - **`5xx` is retried only on non-mutating (`GET`) requests.** A `5xx` on a
   `POST` / `PATCH` / `DELETE` is **not** retried — the request may have executed,
   so a retry risks a double-send (or, for `DELETE`, retrying a lost-but-applied
-  delete into a confusing `404`).
+  delete into a confusing `404`). To retry a `send` / `reply` safely, pass an
+  idempotency key — see [Idempotent sends](#idempotent-sends).
 - **Multipart uploads are never retried** (a retry would re-send the body).
 - **Long `Retry-After` values block up to `max_retry_after_seconds`** (default
   ~67 minutes, sized to ride out hour-bucket rate limits for batch jobs). When a
@@ -112,21 +96,57 @@ contract — read it before relying on retries:
   may be a coroutine (it's awaited); a raising callback is swallowed so it can't
   break the retry.
 
+## Idempotent sends
+
+Because a `5xx` on a send is **not** auto-retried (a blind retry risks a second
+delivery + a second charge), the SDK gives you a way to retry it yourself
+*safely*. `messages.send`, `messages.reply`, and scheduled sends via
+`drafts.create` (with `send_at`) accept an `idempotency_key`: a network-retried
+request carrying the same key produces **at most one** message and one charge —
+the server replays the original outcome and returns the **same `message_id`**
+instead of sending again.
+
+```python
+import uuid
+
+key = str(uuid.uuid4())  # stable per send intent — persist it with the job
+
+# First call sends; a same-key retry replays the first result (no second send).
+sent = rl.messages.send(
+    from_mailbox="support",
+    to="user@example.com",
+    subject="Hi",
+    body="Hello",
+    idempotency_key=key,
+)
+print(sent["message_id"])  # a same-key retry returns this SAME id
+```
+
+The key travels as the `Idempotency-Key` request header and is permanent (no
+expiry). A non-throwing probe, `rl.messages.get_idempotency_replay(key)`, reports
+whether a key already produced a result, is still in flight, or is a miss — call
+it before a retry whose local inputs (a staged attachment, the original message)
+may no longer be available. The async client exposes the same methods.
+
 ## Resources
 
 | Resource | Methods |
 |----------|---------|
-| `rl.mailboxes` | `create`, `list`, `delete`, `update`, `set_recipient_policy` |
+| `rl.domains` | `create`, `list`, `get`, `verify`, `update_self_hosted_config`, `delete`, `set_default`, `recheck` |
+| `rl.mailboxes` | `create`, `list`, `get_mailbox`, `delete`, `update`, `set_recipient_policy`, `set_thread_replies`, `set_agent_send_containment`, `set_agent_send_policy`, `set_attachment_access`, `set_sender_policy` |
 | `rl.mailboxes.allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
-| `rl.messages` | `send`, `list`, `get`, `reply`, `wait`, `release`, `block`, `set_starred` |
+| `rl.mailboxes.inbound_allowlist` | `list`, `add`, `add_bulk`, `delete`, `list_blocked_attempts` |
+| `rl.messages` | `send`, `list`, `get`, `reply`, `get_idempotency_replay`, `wait`, `release`, `block`, `report`, `delete`, `firewall_release`, `mark_read`, `set_starred`, `approve_review`, `deny_review` |
 | `rl.drafts` | `create`, `get`, `list`, `update`, `send`, `delete` |
-| `rl.threads` | `list`, `get`, `set_starred` |
+| `rl.threads` | `list`, `get`, `mark_read`, `set_starred` |
 | `rl.attachments` | `get_download_url`, `get_preview`, `upload`, `get_upload`, `delete_upload` |
 | `rl.webhooks` | `create`, `list`, `get`, `update`, `delete`, `rotate_secret`, `test`, `list_deliveries`, `retry_delivery` |
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
-| `rl.suppressions` | `list`, `delete` |
+| `rl.suppressions` | `list`, `add`, `add_bulk`, `delete` |
+| `rl.inbound_blocklist` | `list`, `add`, `add_bulk`, `delete` |
 | `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
-| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning` |
+| `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning`, `export` |
+| `rl.legal_holds` | `apply`, `release`, `list`, `get` |
 | `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.
@@ -149,7 +169,7 @@ if draft["worst_decision"] == "allow":
 
 The send/reply/draft-send response carries two additive, nullable keys that explain a held send inline (no second `messages.get` call). `result["scan"]` is the vendor-neutral scanner verdict (`ScanSummary`); `result["hold_context"]` (`{"trigger_source", "summary_reasons"}` or `None`) is the policy/HITL reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/HITL hold — a clean scan held for review by your mailbox policy, or a scanner review-flag held as quarantine on a plan without the review queue (`trigger_source`: `mailbox_policy` | `scanner` | `both`).
 
-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.)
+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 decides.** When async dispatch is available the server returns `202` with `status="queued_for_dispatch"` (`AsyncSendAck`); otherwise it ignores the hint and returns a normal `200` `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`, `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`.
@@ -253,7 +273,7 @@ rl.mailboxes.update(
 
 ### Advanced PII config (Pro+)
 
-PR 8 added `pii_redaction_config` for **per-detector** control over redaction (e.g. "leave email visible, redact everything else") and **operator-level** rendering (`partial_mask` for credit cards, `hash_replace` for emails you want to dedupe without exposing). Pro+ feature; only meaningful when `pii_mode="redacted"`.
+`pii_redaction_config` gives **per-detector** control over redaction (e.g. "leave email visible, redact everything else") and **operator-level** rendering (`partial_mask` for credit cards, `hash_replace` for emails you want to dedupe without exposing). Pro+ feature; only meaningful when `pii_mode="redacted"`.
 
 ```python
 # Per-detector toggle: show emails to the agent, keep everything else redacted.
@@ -375,7 +395,7 @@ A send/reply/draft-send to a recipient on your do-not-contact (suppression) list
 
 Allowlist mutations are admin-only — granting send permission to an LLM defeats the containment boundary. Agents *can* `list` (so they can see what they're allowed to email) but not `add`/`add_bulk`/`delete`. Three new webhook events: `recipient_allowlist.added`, `recipient_allowlist.removed`, `mailbox.recipient_policy_changed`.
 
-### Domain entries (sprint 039)
+### Domain entries
 
 Entries can be either an exact email (`alice@corp.com`) or a bare-domain pattern (`@corp.com`) that matches every address at that domain. Exact-domain only — `@corp.com` matches `*@corp.com` but NOT `eve@sub.corp.com`.
 
@@ -400,7 +420,7 @@ Responses expose `pattern_type: "email" | "domain"` on every add/list/delete/bul
 
 Blocklist precedence still holds: a domain-block beats an exact-allow at the same domain. Malformed patterns (`@`, `@.com`, `@foo`, `@corp-.com`, non-ASCII) raise `ReplyLayerError` with `.code == "INVALID_EMAIL"` (message: `"Invalid email or domain pattern"`).
 
-### Blocked attempts (migration 038)
+### Blocked attempts
 
 Every send the allowlist gate rejects writes an append-only audit row and emits a deduped `recipient_allowlist.blocked_attempt` webhook. Review the log to see what your agent tried to email and one-click add legitimate recipients.
 
@@ -443,6 +463,28 @@ if not status["active"] and status["privacy_ok"]:
 
 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(...)`).
 
+## Trusted instruction sources
+
+Every inbound message read carries `agent_safety_context` with `untrusted_content` `True` — the body is external data, not instructions for the agent to act on. Trusted instruction sources is an opt-in, **read-path-only** relaxation of that default for one specific, customer-designated, *verified* sender address per mailbox (address-grain only — there is no domain-wide grant). It does not change what a resulting send is allowed to do; the only related send-side control is a per-mailbox strict-recipient toggle, configured outside the SDK.
+
+The relaxation only applies on a read when **every** layer is satisfied, entirely on the server side: the platform feature is enabled, the mailbox's instruction-trust mode is on, the designated sender's message passed Mailgun sender verification (`verified_aligned`), the message scanned clean and is `available`, and the reading API key is a `role="agent"` key with the per-key capability enabled. There is no client-side opt-in — the SDK does not send any header or constructor flag to request this; a message either qualifies under the operator's configuration or it doesn't, and the response reflects that automatically:
+
+```python
+result = rl.messages.wait(mailbox["id"])
+msg = result["message"]
+ctx = msg.get("agent_safety_context") if msg else None
+if ctx and ctx.get("instruction_trust"):
+    # Gate passed: guidance was REPLACED with trusted-instruction wording (the
+    # agent may act on this verified sender's own explicit request in this
+    # message). untrusted_content is still True — this is metadata, not a
+    # content-safety judgment.
+    print(ctx["guidance"])
+    print(ctx["instruction_trust"])
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+```
+
+A human account owner enables the mailbox mode and the key's capability, and designates the trusted sender, from the dashboard (each a loosening change requiring session re-auth). Both the mailbox mode and the per-key capability default to off, so existing integrations are unaffected until a customer opts in. This is a read-path signal only — a copied or hijacked API key cannot self-grant the capability, and there is nothing for a client to set to request it.
+
 ## 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.
@@ -508,9 +550,9 @@ import json
 payload = json.loads(request.body)
 # payload["event"] is the discriminator — NOT payload["type"]
 if payload["event"] == "message.received":
-    # handle inbound message
+    print("handle inbound message")
 elif payload["event"] == "message.dispatch_failed":
-    # handle failed outbound send
+    print("handle failed outbound send")
 ```
 
 ## Context managers

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.21.0"
+version = "0.22.1"
 description = "Official Python SDK for ReplyLayer — email for AI agents"
 readme = "README.md"
 license = "MIT"
@@ -17,6 +17,11 @@ dependencies = [
   "typing_extensions>=4.0",
 ]
 
+[project.urls]
+Homepage = "https://replylayer.ai"
+Repository = "https://github.com/replylayer/rly"
+Issues = "https://github.com/replylayer/rly/issues"
+
 [project.optional-dependencies]
 # Optional CLI convenience: `pip install "replylayer[cli]"` also installs the
 # `rly` launcher (the `rly` / `replylayer` command-line tools). The SDK itself

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

@@ -28,6 +28,7 @@ from .types import (
     ThreadStarResponse,
     # WS6-SDK — async optimistic-ack (0.16.0).
     AsyncSendAck,
+    WebhookEventType,
     WebhookSummary,
     WebhookDeliverySummary,
     WebhookDeliveryStatus,
@@ -49,6 +50,9 @@ from .types import (
     GetUploadAttachmentResponse,
     # Migration 036 — recipient allowlist types.
     RecipientPolicyMode,
+    # Single "agent sends" control — derived view types.
+    AgentSendPolicy,
+    AgentSendRestrictedBy,
     AllowlistEntry,
     ListAllowlistResponse,
     AddAllowlistResponse,
@@ -70,6 +74,11 @@ from .types import (
     EnableLinkScanningResponse,
     EnableLinkScanningDisclosure,
     AgentSafetyContext,
+    InstructionTrustBasis,
+    # R5 — verified-sender signal.
+    SenderAuthVerdict,
+    SenderAuthentication,
+    SenderAuthenticationCompact,
     # Governed Email-Effect Contract v1 (Track 2).
     EmailEffect,
     EffectStatus,
@@ -92,7 +101,7 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.21.0"
+__version__ = "0.22.1"
 
 __all__ = [
     # Message delete response (0.20.0).
@@ -126,6 +135,7 @@ __all__ = [
     "EmailEffectRetryableError",
     "EmailEffect",
     "EffectStatus",
+    "WebhookEventType",
     "WebhookSummary",
     "WebhookDeliverySummary",
     "WebhookDeliveryStatus",
@@ -146,6 +156,8 @@ __all__ = [
     "ConsumedAttachmentResponse",
     "GetUploadAttachmentResponse",
     "RecipientPolicyMode",
+    "AgentSendPolicy",
+    "AgentSendRestrictedBy",
     "AllowlistEntry",
     "ListAllowlistResponse",
     "AddAllowlistResponse",
@@ -164,6 +176,10 @@ __all__ = [
     "EnableLinkScanningResponse",
     "EnableLinkScanningDisclosure",
     "AgentSafetyContext",
+    "InstructionTrustBasis",
+    "SenderAuthVerdict",
+    "SenderAuthentication",
+    "SenderAuthenticationCompact",
     "MessageReceivedSafetySignal",
     "MessageReceivedWebhookPayload",
     # PR 6 — HITL review queue.

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

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

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

@@ -61,9 +61,9 @@ class WebhookSignatureError(ReplyLayerError):
 
 
 # Migration 040 — scheduled-send error surface. Raised when scheduled-send
-# routes reject a request (invalid TZ / too-soon / too-far / quota breach /
-# Idempotency-Key without send_at). Subclass of ReplyLayerError so generic
-# catches still work; typed .reason_code narrows for per-reason handling.
+# routes reject a request (invalid TZ / too-soon / too-far / quota breach).
+# Subclass of ReplyLayerError so generic catches still work; typed
+# .reason_code narrows for per-reason handling.
 #
 # NOT raised for runtime dispatch failures — those surface as
 # message.dispatch_failed webhook events, not SDK exceptions.
@@ -72,7 +72,6 @@ _SCHEDULING_REASON_CODES: frozenset[str] = frozenset({
     "SEND_AT_TOO_SOON",
     "SEND_AT_TOO_FAR",
     "SCHEDULED_SEND_QUOTA_EXCEEDED",
-    "IDEMPOTENCY_KEY_REQUIRES_SEND_AT",
 })
 
 

{replylayer-0.21.0 → replylayer-0.22.1}/replylayer/resources/mailboxes.py

@@ -5,6 +5,7 @@ from urllib.parse import quote
 
 from .._http import AsyncHttpClient, SyncHttpClient
 from ..types import (
+    AgentSendPolicy,
     AttachmentAccessResponse,
     AttachmentAllowedFileFamilyRequest,
     AttachmentExposureMode,
@@ -456,6 +457,16 @@ class SyncMailboxes:
         # Migration 085 — thread-scoped reply bypass toggle. None means "do not
         # include the field in the PATCH".
         allow_thread_replies: bool | None = None,
+        # Migration 096 — R3 agent-send-containment opt-out (session/admin-only).
+        # None means "do not include the field in the PATCH".
+        agent_send_containment: bool | None = None,
+        # Single "agent sends" convenience control. None means "do not include
+        # the field". Mutually exclusive with raw recipient_policy_mode/
+        # agent_send_containment in the same call (the server returns 400).
+        agent_send_policy: AgentSendPolicy | None = None,
+        # Consent for opening the agent on an allowlist mailbox (also opens
+        # human sends). None/False omits it.
+        confirm_open_human_sends: bool | None = None,
         # PR 8.1 — per-detector redaction visibility. Pass {} to reset to
         # platform default; pass a partial map (e.g.
         # {"EMAIL_ADDRESS": {"redact": False}}) to disable redaction on
@@ -479,6 +490,12 @@ class SyncMailboxes:
             body["hitl_mode"] = hitl_mode
         if allow_thread_replies is not None:
             body["allow_thread_replies"] = allow_thread_replies
+        if agent_send_containment is not None:
+            body["agent_send_containment"] = agent_send_containment
+        if agent_send_policy is not None:
+            body["agent_send_policy"] = agent_send_policy
+        if confirm_open_human_sends:
+            body["confirm_open_human_sends"] = True
         if pii_redaction_config is not None:
             body["pii_redaction_config"] = pii_redaction_config
         return self._http.request("PATCH", f"/v1/mailboxes/{id}", body=body)
@@ -515,6 +532,41 @@ class SyncMailboxes:
         """
         return self.update(id, allow_thread_replies=allow)
 
+    def set_agent_send_containment(self, id: str, enabled: bool) -> dict[str, Any]:
+        """Migration 096 — toggle R3 agent-send-containment for this mailbox.
+
+        When ``True`` (the default), an agent-key send (NOT human/admin/session)
+        on a native-blocklist mailbox is run through the allowlist +
+        thread-participant gate so a hijacked agent can't exfiltrate to a new
+        recipient. Set ``False`` to deliberately open an uncontained agent send
+        path. Session/admin only server-side.
+        """
+        return self.update(id, agent_send_containment=enabled)
+
+    def set_agent_send_policy(
+        self,
+        id: str,
+        policy: AgentSendPolicy,
+        *,
+        confirm_open_human_sends: bool = False,
+    ) -> dict[str, Any]:
+        """Single "agent sends" control — the thin front door over
+        ``recipient_policy_mode`` + ``agent_send_containment`` (no separate
+        stored field). ``"open"`` lets the agent send to any new recipient;
+        ``"restricted"`` gates it. Session/admin only server-side.
+
+        Opening on an allowlist mailbox also opens human sends, so the server
+        returns 409 ``OPEN_AGENT_REQUIRES_OPEN_MAILBOX`` (with
+        ``details.also_opens_human_sends = True``) on the first call. Re-issue
+        with ``confirm_open_human_sends=True`` to atomically flip the mailbox to
+        blocklist + containment off.
+        """
+        return self.update(
+            id,
+            agent_send_policy=policy,
+            confirm_open_human_sends=confirm_open_human_sends,
+        )
+
     def set_sender_policy(
         self,
         id: str,
@@ -648,6 +700,16 @@ class AsyncMailboxes:
         # Migration 085 — thread-scoped reply bypass toggle. None = do not
         # include in the PATCH.
         allow_thread_replies: bool | None = None,
+        # Migration 096 — R3 agent-send-containment opt-out (session/admin-only).
+        # None = do not include in the PATCH.
+        agent_send_containment: bool | None = None,
+        # Single "agent sends" convenience control. None = do not include.
+        # Mutually exclusive with raw recipient_policy_mode/agent_send_containment
+        # in the same call (the server returns 400).
+        agent_send_policy: AgentSendPolicy | None = None,
+        # Consent for opening the agent on an allowlist mailbox (also opens
+        # human sends). None/False omits it.
+        confirm_open_human_sends: bool | None = None,
         # PR 8.1 — per-detector redaction visibility. Pass {} to reset to
         # platform default; pass a partial map to disable redaction on
         # selected detectors. None = do not include in the PATCH.
@@ -668,6 +730,12 @@ class AsyncMailboxes:
             body["hitl_mode"] = hitl_mode
         if allow_thread_replies is not None:
             body["allow_thread_replies"] = allow_thread_replies
+        if agent_send_containment is not None:
+            body["agent_send_containment"] = agent_send_containment
+        if agent_send_policy is not None:
+            body["agent_send_policy"] = agent_send_policy
+        if confirm_open_human_sends:
+            body["confirm_open_human_sends"] = True
         if pii_redaction_config is not None:
             body["pii_redaction_config"] = pii_redaction_config
         return await self._http.request("PATCH", f"/v1/mailboxes/{id}", body=body)
@@ -706,6 +774,39 @@ class AsyncMailboxes:
         """
         return await self.update(id, allow_thread_replies=allow)
 
+    async def set_agent_send_containment(self, id: str, enabled: bool) -> dict[str, Any]:
+        """Migration 096 — toggle R3 agent-send-containment for this mailbox (async).
+
+        When ``True`` (the default), an agent-key send on a native-blocklist
+        mailbox is run through the allowlist + thread-participant gate. Set
+        ``False`` to deliberately open an uncontained agent send path.
+        Session/admin only server-side.
+        """
+        return await self.update(id, agent_send_containment=enabled)
+
+    async def set_agent_send_policy(
+        self,
+        id: str,
+        policy: AgentSendPolicy,
+        *,
+        confirm_open_human_sends: bool = False,
+    ) -> dict[str, Any]:
+        """Single "agent sends" control — the thin front door over
+        ``recipient_policy_mode`` + ``agent_send_containment`` (async).
+
+        ``"open"`` lets the agent send to any new recipient; ``"restricted"``
+        gates it. Session/admin only server-side. Opening on an allowlist
+        mailbox also opens human sends, so the server returns 409
+        ``OPEN_AGENT_REQUIRES_OPEN_MAILBOX``; re-issue with
+        ``confirm_open_human_sends=True`` to atomically flip to blocklist +
+        containment off.
+        """
+        return await self.update(
+            id,
+            agent_send_policy=policy,
+            confirm_open_human_sends=confirm_open_human_sends,
+        )
+
     async def set_sender_policy(
         self,
         id: str,

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

@@ -72,6 +72,8 @@ WebhookEventType = Literal[
     # matching endpoint commits the state transition. Subscribable via
     # POST/PATCH /v1/webhooks.enabled_events.
     "message.review.queued", "message.review.approved", "message.review.denied",
+    # Trusted-instruction-sources — customer grant/revoke of a trusted sender.
+    "trusted_source.granted", "trusted_source.revoked",
     "webhook.test",
 ]
 ApiKeyRole = Literal["admin", "agent"]
@@ -164,6 +166,21 @@ SubaddressMode = Literal["reply_to", "from", "none"]
 #     still runs first (wins on overlap).
 RecipientPolicyMode = Literal["blocklist", "allowlist"]
 
+# Single "agent sends" control — a DERIVED convenience view over
+# recipient_policy_mode + agent_send_containment (no separate stored field).
+#   - "open": the agent may send to any new recipient (blocklist mailbox with
+#     containment off).
+#   - "restricted": the agent is gated (see restricted_by for why).
+# See plans/agent-sends-policy-control-2026-06-26.md.
+AgentSendPolicy = Literal["restricted", "open"]
+
+# When agent_send_policy == "restricted", WHY:
+#   - "mailbox_allowlist": the whole mailbox is allowlist (humans too); opening
+#     the agent would also open human sends.
+#   - "agent_containment": blocklist mailbox + the R3 containment overlay.
+#   - None: agent_send_policy == "open".
+AgentSendRestrictedBy = Literal["mailbox_allowlist", "agent_containment"] | None
+
 # Per-mailbox INBOUND sender firewall mode (migration 047). Symmetric
 # counterpart to RecipientPolicyMode for the inbound side.
 #   - blocklist (default): inbound_sender_blocklists is the only ingest gate.
@@ -381,6 +398,12 @@ class CreateMailboxResponse(TypedDict):
     hitl_mode: HitlMode
     # Migration 085 — thread-scoped reply bypass flag; new mailboxes default True.
     allow_thread_replies: bool
+    # Migration 096 — R3 agent-send-containment opt-out; new mailboxes default True.
+    agent_send_containment: bool
+    # Single "agent sends" control — DERIVED from the two raw fields above.
+    agent_send_policy: AgentSendPolicy
+    # Why the agent is restricted (None when agent_send_policy == "open").
+    restricted_by: AgentSendRestrictedBy
 
 
 class Mailbox(TypedDict):
@@ -426,6 +449,18 @@ class Mailbox(TypedDict):
     # in allowlist mode permits a reply/follow-up to a visible inbound thread
     # participant without a standing grant.
     allow_thread_replies: bool
+    # Migration 096 — R3 agent-send-containment opt-out. When True (the default),
+    # an agent-key send on a native-blocklist mailbox is run through the
+    # allowlist + thread-participant gate. Strict no-op on native-allowlist.
+    agent_send_containment: bool
+    # Trusted-instruction-sources — per-mailbox master switch + strict-recipient
+    # policy. NotRequired for rollout tolerance (a pre-slice-6b server omits them).
+    instruction_trust_mode: NotRequired[Literal["disabled", "enabled"]]
+    instruction_trust_strict_recipient: NotRequired[bool]
+    # Single "agent sends" control — DERIVED from the two raw fields above.
+    agent_send_policy: AgentSendPolicy
+    # Why the agent is restricted (None when agent_send_policy == "open").
+    restricted_by: AgentSendRestrictedBy
     # PR 8.1 — per-detector redaction visibility. None = platform default
     # (all 13 detectors redact with `<TYPE>` placeholder). Populated value
     # is a partial map keyed by detector type; tier-gated Pro+ for any
@@ -467,6 +502,12 @@ class UpdateMailboxResponse(TypedDict):
     hitl_mode: HitlMode
     # Migration 085 — thread-scoped reply bypass flag.
     allow_thread_replies: bool
+    # Migration 096 — R3 agent-send-containment opt-out.
+    agent_send_containment: bool
+    # Single "agent sends" control — DERIVED from the two raw fields above.
+    agent_send_policy: AgentSendPolicy
+    # Why the agent is restricted (None when agent_send_policy == "open").
+    restricted_by: AgentSendRestrictedBy
     # PR 8.1 — per-detector redaction visibility (None = platform default).
     pii_redaction_config: PiiRedactionConfig | None
 
@@ -705,6 +746,8 @@ class MessageSummary(TypedDict, total=False):
     scan: NotRequired["ScanSummary | None"]
     # Phase 5 — inbound untrusted-body contract (present even on a clean scan); null/absent for outbound.
     agent_safety_context: NotRequired["AgentSafetyContext | None"]
+    # R5 — compact verified-sender signal {verdict}; None = not evaluated.
+    sender_authentication: NotRequired["SenderAuthenticationCompact | None"]
     # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
     subaddress_instance_id: Required[str | None]
     # Migration 047 — present (non-null) only on state='firewall_blocked'.
@@ -907,6 +950,7 @@ ScanCategory = Literal[
     "recipient_policy",
     "secret_detected",
     "content_similarity",
+    "delivery_warmup",
     "scan_incomplete",
 ]
 
@@ -973,6 +1017,26 @@ class ScanSummary(TypedDict):
     findings: list[ScanFinding]
 
 
+class InstructionTrustBasis(TypedDict):
+    """Trusted-instruction-sources — thin BASIS metadata on a trusted-instruction
+    message (plan §4). Present ONLY when the customer designated this verified
+    sender as a trusted instruction source AND the reading credential is a
+    ``role='agent'`` key with the per-key capability enabled. Relaxation is
+    gated purely by operator server-side config (mailbox instruction-trust
+    mode + per-key capability + a live trusted-source grant) plus the
+    message's authenticity/scan state — there is no client-sent opt-in header
+    or constructor flag. The behavioural contract is in
+    ``AgentSafetyContext.guidance`` (REPLACED on a trusted message); this is
+    metadata only. ``untrusted_content`` stays True."""
+
+    version: Literal["v1"]
+    match: Literal["address"]
+    # Verified sender's domain; None under pii_mode=redacted.
+    verified_domain: str | None
+    verdict: Literal["verified_aligned"]
+    provenance: Literal["mailgun"]
+
+
 class AgentSafetyContext(TypedDict):
     """Top-level standing safety contract on inbound message reads + the
     ``message.received`` webhook. Present (untrusted_content=True) on every
@@ -981,6 +1045,41 @@ class AgentSafetyContext(TypedDict):
 
     untrusted_content: bool
     guidance: str
+    # Present ONLY on a trusted-instruction message (gate passed + opted-in
+    # credential). When present, ``guidance`` carries the trusted-message
+    # instruction; this is thin metadata, not the contract.
+    instruction_trust: NotRequired[InstructionTrustBasis]
+
+
+# R5 — verified-sender verdict. High-confidence DOMAIN authenticity, NOT
+# certainty: ``verified_aligned`` means the message genuinely originated from
+# its From domain (Mailgun DMARC pass + alignment); it does NOT prove the
+# person/account, lookalike-safety, or content-safety, and never relaxes the
+# inbound-untrusted contract. Tolerant reader: treat an unknown value as
+# unverified. ``None`` (the whole object) = not evaluated.
+SenderAuthVerdict = Literal[
+    "verified_aligned",
+    "authenticated_unaligned",
+    "failed",
+    "none",
+    "error",
+]
+
+
+class SenderAuthentication(TypedDict):
+    """Full verified-sender signal on the detail surface. ``from_domain`` +
+    ``signing_domain`` are nulled under ``pii_mode='redacted'``."""
+
+    verdict: SenderAuthVerdict
+    from_domain: str | None
+    signing_domain: str | None
+    provenance: Literal["mailgun", "self_hosted_imap"]
+
+
+class SenderAuthenticationCompact(TypedDict):
+    """Compact verified-sender signal on the list/wait surfaces."""
+
+    verdict: SenderAuthVerdict
 
 
 ScanView = Literal["summary", "verbose"]
@@ -1017,6 +1116,9 @@ class GetMessageResponse(TypedDict, total=False):
     attachments: Required[list[MessageAttachment]]
     scan: Required[ScanSummary | None]
     agent_safety_context: NotRequired["AgentSafetyContext | None"]
+    # R5 — full verified-sender signal; domains nulled under pii_mode=redacted;
+    # None = not evaluated.
+    sender_authentication: NotRequired["SenderAuthentication | 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.
@@ -1650,6 +1752,9 @@ class ApiKeySummary(TypedDict):
     mailbox_ids: list[str]
     created_at: str
     last_used_at: str | None
+    # Trusted-instruction-sources — the per-key opt-in capability (slice 6b).
+    # Only an agent key can hold it. NotRequired for rollout tolerance.
+    instruction_trust_enabled: NotRequired[bool]
 
 
 class ListApiKeysResponse(TypedDict):
@@ -1711,12 +1816,26 @@ class QuotaToday(TypedDict):
     day: str
 
 
+# Present ONLY while a new paid account is inside its shared-domain warm-up
+# window (paid-velocity-gate); absent for every other account/state. `until`
+# is ISO-8601; `shared_domain_daily_limit` is the temporary daily send cap on
+# the shared platform pool; `velocity_gate_mode` reflects whether the inline
+# velocity control is enforcing yet; `reason` is customer-safe copy. Verify
+# your own sending domain (BYOD) to lift the warm-up immediately.
+class QuotaWarmup(TypedDict):
+    until: str
+    shared_domain_daily_limit: int
+    velocity_gate_mode: Literal["log_only", "enforced"]
+    reason: str
+
+
 class QuotaResponse(TypedDict):
     today: QuotaToday
     sends_remaining: int
     reset_at: str
     scope: Literal["admin", "agent"]
     bound_mailbox_ids: list[str]
+    warmup: NotRequired[QuotaWarmup]
 
 
 # Malicious link scanning (URL reputation, backed by Google Web Risk).

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

@@ -233,6 +233,59 @@ async def test_async_mailboxes_create_with_self_hosted_imap_folder():
     await rl.aclose()
 
 
+# ── Single "agent sends" control — set_agent_send_policy body shape (async) ──
+# plans/agent-sends-policy-control-2026-06-26.md.
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_set_agent_send_policy_sends_policy_alone_without_confirm():
+    """Async helper sends ONLY agent_send_policy when no confirm flag is passed."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    rl = async_sdk()
+    await rl.mailboxes.set_agent_send_policy("m1", "restricted")
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "restricted"}
+    assert "confirm_open_human_sends" not in payload
+    await rl.aclose()
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_set_agent_send_policy_includes_confirm_only_when_true():
+    """Async helper forwards confirm_open_human_sends=True on the open-allowlist
+    confirmation path."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    rl = async_sdk()
+    await rl.mailboxes.set_agent_send_policy(
+        "m1", "open", confirm_open_human_sends=True,
+    )
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "open", "confirm_open_human_sends": True}
+    await rl.aclose()
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_set_agent_send_policy_omits_confirm_when_false():
+    """A falsy confirm_open_human_sends does NOT add the flag to the async body."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    rl = async_sdk()
+    await rl.mailboxes.set_agent_send_policy(
+        "m1", "restricted", confirm_open_human_sends=False,
+    )
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "restricted"}
+    assert "confirm_open_human_sends" not in payload
+    await rl.aclose()
+
+
 @respx.mock
 @pytest.mark.asyncio
 async def test_async_mailboxes_set_attachment_access_posts_legacy_shape_without_unset_keys():

{replylayer-0.21.0 → replylayer-0.22.1}/tests/test_drafts.py

@@ -472,19 +472,19 @@ def test_drafts_create_429_quota_exceeded_maps_to_scheduling_error_not_rate_limi
 
 
 @respx.mock
-def test_drafts_create_idempotency_key_without_send_at_maps_to_scheduling_error():
+def test_drafts_create_send_at_too_far_maps_to_scheduling_error():
     respx.post(f"{BASE}/v1/drafts").mock(
         return_value=httpx.Response(400, json={
-            "error": "Idempotency-Key is only accepted when send_at is present",
-            "code": "IDEMPOTENCY_KEY_REQUIRES_SEND_AT",
+            "error": "send_at is beyond the scheduling horizon",
+            "code": "SEND_AT_TOO_FAR",
         }),
     )
     with pytest.raises(SchedulingError) as excinfo:
         sdk().drafts.create(
             mailbox_id="mbx1", to="r@example.com", subject="x", body="y",
-            idempotency_key="k1",
+            send_at="2099-01-01T09:00:00Z",
         )
-    assert excinfo.value.reason_code == "IDEMPOTENCY_KEY_REQUIRES_SEND_AT"
+    assert excinfo.value.reason_code == "SEND_AT_TOO_FAR"
 
 
 @respx.mock

replylayer-0.22.1/tests/test_instruction_trust.py

@@ -0,0 +1,37 @@
+"""
+Python SDK — trusted-instruction-sources READ MIRROR.
+
+Design change (option 2): relaxation is gated purely by operator server-side
+config (mailbox instruction_trust_mode + per-key instruction_trust_enabled +
+a live trusted-source grant) plus the message's authenticity/scan state.
+There is no client-sent opt-in header or constructor flag anymore — the SDK
+only reads and types the ``instruction_trust`` basis the server may attach to
+``agent_safety_context`` on a response.
+"""
+
+from replylayer import InstructionTrustBasis
+
+
+def test_instruction_trust_basis_type_is_exported():
+    # The read-mirror type is part of the public surface (parity with the TS SDK).
+    basis: InstructionTrustBasis = {
+        "version": "v1",
+        "match": "address",
+        "verified_domain": "partner.com",
+        "verdict": "verified_aligned",
+        "provenance": "mailgun",
+    }
+    assert basis["verified_domain"] == "partner.com"
+
+
+def test_webhook_event_types_include_trusted_source():
+    # P2 drift pin — the SDK WebhookEventType mirror must carry the slice-4b
+    # trusted-source events (parity with shared/server), else typed callers
+    # cannot subscribe without casts.
+    import typing
+
+    from replylayer import WebhookEventType
+
+    members = set(typing.get_args(WebhookEventType))
+    assert "trusted_source.granted" in members
+    assert "trusted_source.revoked" in members

replylayer-0.22.1/tests/test_readme_resource_parity.py

@@ -0,0 +1,80 @@
+"""B6 parity gate — the README "Resources" table must list EVERY public method
+of EVERY resource the client exposes, and nothing that isn't a real method.
+
+A stale table is the failure this locks out (the docs had drifted to
+"suppressions has only list/delete" and "messages has 7 of 15 methods").
+Reflect over a live client, parse the README table, and assert set equality so
+adding/removing a method fails CI until the table is regenerated.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+from pathlib import Path
+
+from replylayer import ReplyLayer
+
+README_PATH = Path(__file__).resolve().parent.parent / "README.md"
+
+
+def _method_names(obj: object) -> list[str]:
+    """Public bound-method names on a resource instance, sorted.
+
+    ``inspect.ismethod`` returns only bound methods, so ``@staticmethod``
+    helpers (e.g. ``webhooks.verify_signature``) are excluded — matching the
+    table, which documents the top-level ``verify_webhook_signature`` helper
+    separately, not as a resource method.
+    """
+    return sorted(
+        name
+        for name, _ in inspect.getmembers(obj, predicate=inspect.ismethod)
+        if not name.startswith("_")
+    )
+
+
+def _build_actual() -> dict[str, list[str]]:
+    out: dict[str, list[str]] = {}
+    with ReplyLayer(api_key="rly_live_test") as client:
+        for res_name, resource in vars(client).items():
+            if res_name.startswith("_"):
+                continue
+            out[res_name] = _method_names(resource)
+            # One level of nested resources (e.g. mailboxes.allowlist). The
+            # shared HTTP client is stored as the private ``_http`` attribute
+            # and is filtered out by the underscore guard.
+            for sub_name, sub in vars(resource).items():
+                if sub_name.startswith("_"):
+                    continue
+                if _method_names(sub):
+                    out[f"{res_name}.{sub_name}"] = _method_names(sub)
+    return out
+
+
+def _parse_readme_table(md: str) -> dict[str, list[str]]:
+    out: dict[str, list[str]] = {}
+    for raw in md.splitlines():
+        line = raw.strip()
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.split("|")]
+        resource_cell = cells[1] if len(cells) > 1 else ""
+        m = re.match(r"^`rl\.(.+)`$", resource_cell)
+        if not m:  # header / separator / non-resource rows
+            continue
+        methods_cell = cells[2] if len(cells) > 2 else ""
+        out[m.group(1)] = sorted(re.findall(r"`([^`]+)`", methods_cell))
+    return out
+
+
+_ACTUAL = _build_actual()
+_DOCUMENTED = _parse_readme_table(README_PATH.read_text(encoding="utf-8"))
+
+
+def test_readme_documents_all_resources() -> None:
+    assert sorted(_DOCUMENTED) == sorted(_ACTUAL)
+
+
+def test_readme_lists_all_methods() -> None:
+    for key, methods in _ACTUAL.items():
+        assert _DOCUMENTED.get(key) == methods, f"methods for rl.{key}"

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

@@ -53,6 +53,21 @@ def test_account_get_usage_includes_storage():
     assert res["storage"]["breakdown"]["derivative_bytes"] == 34
 
 
+QUOTA_RESPONSE_WARMUP = {
+    "today": {"count": 2, "limit": 233, "day": "2026-07-01"},
+    "sends_remaining": 231,
+    "reset_at": "2026-07-02T00:00:00.000Z",
+    "scope": "admin",
+    "bound_mailbox_ids": [],
+    "warmup": {
+        "until": "2026-07-04T12:00:00.000Z",
+        "shared_domain_daily_limit": 233,
+        "velocity_gate_mode": "log_only",
+        "reason": "New paid accounts ramp to full sending volume over their first few days on the shared pool.",
+    },
+}
+
+
 @respx.mock
 def test_account_get_quota_returns_send_budget():
     route = respx.get(f"{BASE}/v1/accounts/quota").mock(return_value=httpx.Response(200, json=QUOTA_RESPONSE))
@@ -63,6 +78,21 @@ def test_account_get_quota_returns_send_budget():
     assert res["reset_at"] == "2026-05-31T00:00:00.000Z"
     assert res["scope"] == "agent"
     assert res["bound_mailbox_ids"] == ["mb-1", "mb-2"]
+    # `warmup` is optional and absent for a non-warm-up account.
+    assert "warmup" not in res
+
+
+@respx.mock
+def test_account_get_quota_passes_through_warmup():
+    route = respx.get(f"{BASE}/v1/accounts/quota").mock(
+        return_value=httpx.Response(200, json=QUOTA_RESPONSE_WARMUP)
+    )
+    res = sdk().account.get_quota()
+    assert route.called
+    assert res["warmup"]["until"] == "2026-07-04T12:00:00.000Z"
+    assert res["warmup"]["shared_domain_daily_limit"] == 233
+    assert res["warmup"]["velocity_gate_mode"] == "log_only"
+    assert "ramp" in res["warmup"]["reason"]
 
 
 @respx.mock
@@ -550,6 +580,51 @@ def test_set_recipient_policy_passes_scanner_policy_when_provided():
     }
 
 
+# ── Single "agent sends" control — set_agent_send_policy body shape (sync) ──
+# plans/agent-sends-policy-control-2026-06-26.md.
+
+
+@respx.mock
+def test_set_agent_send_policy_sends_policy_alone_without_confirm():
+    """The convenience helper sends ONLY agent_send_policy when no confirm flag
+    is passed — confirm_open_human_sends must NOT ride along (default False)."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    sdk().mailboxes.set_agent_send_policy("m1", "restricted")
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "restricted"}
+    assert "confirm_open_human_sends" not in payload
+
+
+@respx.mock
+def test_set_agent_send_policy_includes_confirm_only_when_true():
+    """confirm_open_human_sends=True is forwarded; the consent flag rides along
+    only on the open-allowlist confirmation path."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    sdk().mailboxes.set_agent_send_policy(
+        "m1", "open", confirm_open_human_sends=True,
+    )
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "open", "confirm_open_human_sends": True}
+
+
+@respx.mock
+def test_set_agent_send_policy_omits_confirm_when_false():
+    """A falsy confirm_open_human_sends does NOT add the flag to the body."""
+    route = respx.patch(f"{BASE}/v1/mailboxes/m1").mock(
+        return_value=httpx.Response(200, json={"id": "m1", "name": "support"}),
+    )
+    sdk().mailboxes.set_agent_send_policy(
+        "m1", "restricted", confirm_open_human_sends=False,
+    )
+    payload = json.loads(route.calls[0].request.content)
+    assert payload == {"agent_send_policy": "restricted"}
+    assert "confirm_open_human_sends" not in payload
+
+
 # ── PR 8.1 — pii_redaction_config request forwarding (round-5 audit fix #3) ──