replylayer 0.22.0__tar.gz → 0.23.0__tar.gz

replylayer-0.22.0/README.md → replylayer-0.23.0/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.4
+Name: replylayer
+Version: 0.23.0
+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.
@@ -130,12 +187,12 @@ if draft["worst_decision"] == "allow":
     print(f"Sent {result['message_id']}")
 ```
 
-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`).
+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/human-review reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/human-review 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`.
+- `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/human-review decision drove the hold, `hold_context`.
 - `DRAFT_ALREADY_SENT` — the draft was already sent (race or retry after success).
 
 ```python
@@ -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.
@@ -330,11 +387,11 @@ Images are a separately confirmed raw-download family. When `allowed_file_famili
 
 Human dashboard sessions and admin/pre-scoping keys can download clean stored `metadata_only` attachments, including attachments held back from agent raw-download policy. Agent-role keys remain bound to the mailbox policy gate plus hard safety checks; all callers remain blocked by infected AV verdicts, non-terminal message states, missing stored bytes, and hard attachment blocks.
 
-See ENDPOINTS.md for the full contract and known limitations.
+See the Mailboxes API reference at https://replylayer.ai/docs/api/mailboxes for the full contract and known limitations.
 
 ### Recipient allowlist (mailbox containment)
 
-A mailbox is in `blocklist` mode by default — the pre-send gate rejects `suppressed_addresses` hits and allows everyone else. Switching to `allowlist` mode restricts outbound to a pre-approved list; an agent (or a compromised API key) physically cannot email outside the list.
+A mailbox is in `blocklist` mode by default — the pre-send gate rejects `suppressed_addresses` hits and allows everyone else. Switching to `allowlist` mode contains **agent-origin** outbound to a pre-approved list (plus thread participants): a prompt-injected or compromised **agent key** cannot email outside the list. It is a containment boundary against a hijacked agent, not an all-origin lock — a human send (your dashboard session or an admin API key) is not restricted by the allowlist; only your do-not-contact (suppression) list binds a human send.
 
 ```python
 # Populate the allowlist first. Admin-only — agent keys get 403 INSUFFICIENT_SCOPE.
@@ -356,9 +413,9 @@ rl.mailboxes.allowlist.delete(mailbox["id"], "partner@corp.com", force_empty=Tru
 
 A send/reply/draft-send to a recipient on your do-not-contact (suppression) list raises `ReplyLayerError` with `.code == "RECIPIENT_SUPPRESSED"` (HTTP 403, `details["reason"] == "suppressed"`). This is terminal — escalate, don't retry; remove the suppression or send to a different recipient.
 
-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`.
+Allowlist mutations are admin-only — granting mutation to an LLM defeats the agent-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.
 
@@ -443,7 +500,7 @@ if ctx and ctx.get("instruction_trust"):
     # content-safety judgment.
     print(ctx["guidance"])
     print(ctx["instruction_trust"])
-    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "managed"}
 ```
 
 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.
@@ -492,7 +549,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see https://replylayer.ai/docs/webhooks.
 
 ```python
 from replylayer import verify_webhook_signature
@@ -513,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.22.0/PKG-INFO → replylayer-0.23.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: replylayer
-Version: 0.22.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.
@@ -147,12 +167,12 @@ if draft["worst_decision"] == "allow":
     print(f"Sent {result['message_id']}")
 ```
 
-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`).
+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/human-review reason, non-null only when the delivery `status` diverges from `scan["verdict"]` because of a policy/human-review 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`.
+- `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/human-review decision drove the hold, `hold_context`.
 - `DRAFT_ALREADY_SENT` — the draft was already sent (race or retry after success).
 
 ```python
@@ -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.
@@ -347,11 +367,11 @@ Images are a separately confirmed raw-download family. When `allowed_file_famili
 
 Human dashboard sessions and admin/pre-scoping keys can download clean stored `metadata_only` attachments, including attachments held back from agent raw-download policy. Agent-role keys remain bound to the mailbox policy gate plus hard safety checks; all callers remain blocked by infected AV verdicts, non-terminal message states, missing stored bytes, and hard attachment blocks.
 
-See ENDPOINTS.md for the full contract and known limitations.
+See the Mailboxes API reference at https://replylayer.ai/docs/api/mailboxes for the full contract and known limitations.
 
 ### Recipient allowlist (mailbox containment)
 
-A mailbox is in `blocklist` mode by default — the pre-send gate rejects `suppressed_addresses` hits and allows everyone else. Switching to `allowlist` mode restricts outbound to a pre-approved list; an agent (or a compromised API key) physically cannot email outside the list.
+A mailbox is in `blocklist` mode by default — the pre-send gate rejects `suppressed_addresses` hits and allows everyone else. Switching to `allowlist` mode contains **agent-origin** outbound to a pre-approved list (plus thread participants): a prompt-injected or compromised **agent key** cannot email outside the list. It is a containment boundary against a hijacked agent, not an all-origin lock — a human send (your dashboard session or an admin API key) is not restricted by the allowlist; only your do-not-contact (suppression) list binds a human send.
 
 ```python
 # Populate the allowlist first. Admin-only — agent keys get 403 INSUFFICIENT_SCOPE.
@@ -373,9 +393,9 @@ rl.mailboxes.allowlist.delete(mailbox["id"], "partner@corp.com", force_empty=Tru
 
 A send/reply/draft-send to a recipient on your do-not-contact (suppression) list raises `ReplyLayerError` with `.code == "RECIPIENT_SUPPRESSED"` (HTTP 403, `details["reason"] == "suppressed"`). This is terminal — escalate, don't retry; remove the suppression or send to a different recipient.
 
-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`.
+Allowlist mutations are admin-only — granting mutation to an LLM defeats the agent-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.
 
@@ -460,7 +480,7 @@ if ctx and ctx.get("instruction_trust"):
     # content-safety judgment.
     print(ctx["guidance"])
     print(ctx["instruction_trust"])
-    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "managed"}
 ```
 
 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.
@@ -509,7 +529,7 @@ Error classes: `ReplyLayerError` (base), `AuthenticationError` (401), `Forbidden
 
 ## Webhook signature verification
 
-> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see the hosted webhook docs (coming).
+> For a full integration guide (event catalog, retry behavior, idempotency, security, troubleshooting), see https://replylayer.ai/docs/webhooks.
 
 ```python
 from replylayer import verify_webhook_signature
@@ -530,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.22.0 → replylayer-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.22.0"
+version = "0.23.0"
 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.22.0 → replylayer-0.23.0}/replylayer/__init__.py

@@ -101,7 +101,7 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"
 
 __all__ = [
     # Message delete response (0.20.0).

{replylayer-0.22.0 → replylayer-0.23.0}/replylayer/_http.py

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

{replylayer-0.22.0 → replylayer-0.23.0}/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.22.0 → replylayer-0.23.0}/replylayer/resources/mailboxes.py

@@ -464,8 +464,9 @@ class SyncMailboxes:
         # 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.
+        # Deprecated + ignored by the server: opening the agent on an allowlist
+        # mailbox no longer requires consent (the allowlist only bound the
+        # agent). Kept for back-compat. 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.
@@ -555,11 +556,12 @@ class SyncMailboxes:
         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.
+        Opening on an allowlist mailbox now succeeds directly — the server
+        atomically flips the mailbox to blocklist and clears agent containment.
+        No consent is required (the allowlist only ever bound the agent, so
+        opening it does not affect human sends). ``confirm_open_human_sends`` is
+        **deprecated and ignored** by the server; it is still accepted here for
+        back-compat.
         """
         return self.update(
             id,
@@ -707,8 +709,9 @@ class AsyncMailboxes:
         # 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.
+        # Deprecated + ignored by the server: opening the agent on an allowlist
+        # mailbox no longer requires consent (the allowlist only bound the
+        # agent). Kept for back-compat. 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
@@ -796,10 +799,11 @@ class AsyncMailboxes:
 
         ``"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.
+        mailbox now succeeds directly — the server atomically flips the mailbox
+        to blocklist and clears agent containment, with no consent required
+        (human sends are never allowlist-restricted). ``confirm_open_human_sends``
+        is **deprecated and ignored** by the server; still accepted for
+        back-compat.
         """
         return await self.update(
             id,

{replylayer-0.22.0 → replylayer-0.23.0}/replylayer/types.py

@@ -175,8 +175,8 @@ RecipientPolicyMode = Literal["blocklist", "allowlist"]
 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.
+#   - "mailbox_allowlist": the mailbox is in allowlist mode — the AGENT is
+#     restricted to the allowlist; human sends are unaffected (agent-only).
 #   - "agent_containment": blocklist mailbox + the R3 containment overlay.
 #   - None: agent_send_policy == "open".
 AgentSendRestrictedBy = Literal["mailbox_allowlist", "agent_containment"] | None
@@ -204,7 +204,7 @@ class FirewallBlock(TypedDict):
     matched_field: Literal["envelope", "from"] | None
     matched_pattern: str | None
     reason_code: Literal["SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST"]
-    source_table: Literal["inbound_sender_blocklists", "inbound_sender_allowlists"] | None
+    matched_list: Literal["account_blocklist", "mailbox_allowlist"] | None
     mode: SenderPolicyMode
 
 # Sprint 039 — allowlist + suppression entries may be either an exact email
@@ -413,30 +413,32 @@ class Mailbox(TypedDict):
     status: MailboxStatus
     scanner_policy: ScannerPolicy | None
     pii_mode: PiiMode
-    # Legacy attachment-access acceptance flag (migration 034). Retained for
-    # backward-compatible reads and audit history, but effective attachment
-    # exposure now comes from `attachment_exposure_mode` when set; otherwise
-    # the mailbox behaves as `metadata_only`.
-    attachment_access_enabled: bool
-    attachment_access_accepted_at: str | None
-    attachment_access_accepted_version: str | None
+    # Attachment / outbound-attachment CONSENT bookkeeping. SESSION-ONLY: the
+    # API returns these only to a dashboard (session-cookie) caller and strips
+    # them from every Bearer / API-key response — which includes this SDK. They
+    # drive the human re-acceptance banner and an agent cannot act on them (the
+    # acceptance routes are session + re-auth only), so they are NotRequired and,
+    # for SDK callers, always absent. Read `attachment_exposure_mode` instead.
+    attachment_access_enabled: NotRequired[bool]
+    attachment_access_accepted_at: NotRequired[str | None]
+    attachment_access_accepted_version: NotRequired[str | None]
     attachment_exposure_mode: AttachmentExposureMode
     attachment_allowed_file_families: list[AttachmentAllowedFileFamily]
-    attachment_reauth_at: str | None
-    attachment_policy_version: str | None
-    image_raw_download_confirmed: bool
-    current_image_risk_version: str
-    attachment_image_access_accepted_at: str | None
-    attachment_image_access_accepted_version: str | None
-    # Always the current disclaimer version. Compare to accepted_version to
-    # detect when a "disclaimer updated" banner should render.
-    current_disclaimer_version: str
+    attachment_reauth_at: NotRequired[str | None]
+    attachment_policy_version: NotRequired[str | None]
+    image_raw_download_confirmed: NotRequired[bool]
+    current_image_risk_version: NotRequired[str]
+    attachment_image_access_accepted_at: NotRequired[str | None]
+    attachment_image_access_accepted_version: NotRequired[str | None]
+    # The current disclaimer version, for the dashboard re-acceptance banner.
+    # Session-only (see the consent note above) — absent on SDK/API-key reads.
+    current_disclaimer_version: NotRequired[str]
     # True when the mailbox is on the legacy compat path
     # (attachment_exposure_mode is null but attachment_access_enabled is true).
     # Drives the dashboard re-acceptance banner; flips to false after the
-    # customer accepts an explicit mode. See
-    # docs/runbooks/legacy-attachment-access-migration.md.
-    legacy_wildcard_active: bool
+    # customer accepts an explicit mode. Session-only — absent on SDK/API-key
+    # reads. See docs/runbooks/legacy-attachment-access-migration.md.
+    legacy_wildcard_active: NotRequired[bool]
     # Migration 035 — default outbound sub-addressing rewrite mode.
     default_subaddress_mode: SubaddressMode
     # Migration 036 — recipient policy mode.
@@ -950,6 +952,7 @@ ScanCategory = Literal[
     "recipient_policy",
     "secret_detected",
     "content_similarity",
+    "delivery_warmup",
     "scan_incomplete",
 ]
 
@@ -1033,7 +1036,7 @@ class InstructionTrustBasis(TypedDict):
     # Verified sender's domain; None under pii_mode=redacted.
     verified_domain: str | None
     verdict: Literal["verified_aligned"]
-    provenance: Literal["mailgun"]
+    provenance: Literal["managed"]
 
 
 class AgentSafetyContext(TypedDict):
@@ -1072,7 +1075,7 @@ class SenderAuthentication(TypedDict):
     verdict: SenderAuthVerdict
     from_domain: str | None
     signing_domain: str | None
-    provenance: Literal["mailgun", "self_hosted_imap"]
+    provenance: Literal["managed", "self_hosted_imap"]
 
 
 class SenderAuthenticationCompact(TypedDict):
@@ -1815,12 +1818,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.22.0 → replylayer-0.23.0}/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.0 → replylayer-0.23.0}/tests/test_hitl_review_types.py

@@ -45,7 +45,7 @@ def test_review_queued_payload_constructs_with_required_fields() -> None:
         "direction": "outbound",
         "subject": "Quarterly review",
         "recipient": "ceo@corp.example",
-        "summary_reasons": ["Mailbox requires human approval for outbound mail (hitl_mode=all_outbound)"],
+        "summary_reasons": ['This mailbox requires human approval for all outbound mail (review setting: "All outbound").'],
         "origin": "fresh_send",
     }
     assert payload["origin"] == "fresh_send"

{replylayer-0.22.0 → replylayer-0.23.0}/tests/test_instruction_trust.py

@@ -19,7 +19,7 @@ def test_instruction_trust_basis_type_is_exported():
         "match": "address",
         "verified_domain": "partner.com",
         "verdict": "verified_aligned",
-        "provenance": "mailgun",
+        "provenance": "managed",
     }
     assert basis["verified_domain"] == "partner.com"
 

replylayer-0.23.0/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.22.0 → replylayer-0.23.0}/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