replylayer 0.22.1__tar.gz → 0.26.0__tar.gz

{replylayer-0.22.1 → replylayer-0.26.0}/.gitignore

@@ -4,7 +4,11 @@ dist/
 .env.*
 *.env
 !.env.example
-.claude/
+# .claude is session-local (worktrees, local settings) EXCEPT the shared
+# subagent definitions, which are repo-versioned (plays with `.claude/*`
+# rather than `.claude/` so the re-include below can take effect).
+.claude/*
+!.claude/agents/
 .antigravitycli/
 *.log
 coverage/

{replylayer-0.22.1 → replylayer-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: replylayer
-Version: 0.22.1
+Version: 0.26.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
@@ -164,13 +164,45 @@ may no longer be available. The async client exposes the same methods.
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
 | `rl.suppressions` | `list`, `add`, `add_bulk`, `delete` |
 | `rl.inbound_blocklist` | `list`, `add`, `add_bulk`, `delete` |
-| `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
+| `rl.api_keys` | `create`, `list`, `update`, `revoke`, `rotate`* |
 | `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning`, `export` |
 | `rl.legal_holds` | `apply`, `release`, `list`, `get` |
 | `rl.health` | `check` |
+| `rl.simulator` | `inject_inbound` |
+| `rl.policy` | `get_mailbox_policy`, `get_overview`, `get_account_policy`, `update_account_policy`, `preview_mailbox_policy` |
 
 *`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.
 
+## Simulator
+
+Outbound scenarios use the normal send methods. Inbound scenarios use
+`rl.simulator.inject_inbound()`:
+
+```python
+outbound = rl.messages.send(
+    from_mailbox=mailbox["name"],
+    to="delivered+ci-run-42@simulator.replylayer.net",
+    subject="simulator check",
+    body="exercise the delivered path",
+)
+
+inbound = rl.simulator.inject_inbound({
+    "mailbox_id": mailbox["id"],
+    "scenario": "clean",
+    "label": "ci-run-42",
+})
+
+# Branch on the result: available | quarantined | pending.
+print(outbound["message_id"], inbound["status"], inbound.get("message_id"))
+```
+
+Outbound delivery, bounce, complaint, and suppression addresses; delayed webhook
+outcomes; inbound scenario semantics; and billing/suppression caveats are defined in
+the [email simulator guide](https://replylayer.ai/docs/guides/simulator).
+One Sandbox account can run all four exact outbound scenarios in the same day; those
+addresses bypass destination-concentration controls but still consume normal
+daily/cumulative usage allowance.
+
 ## Drafts: scan-then-review-then-send
 
 `rl.drafts.create()` runs the outbound scanner synchronously and attaches the verdict to the draft. The create-time verdict is UX — it lets an agent (or a human approver) see the likely outcome before clicking send. `rl.drafts.send()` **re-runs the scanner authoritatively** against the mailbox's current policy, so a stale cached verdict cannot slip through.
@@ -187,12 +219,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", "review_causes"?, "agent_instructions"}` or `None`) is the policy/human-review reason plus held-send guidance, non-None on held sends — a typed policy cause (first-contact/send-window/Supervised), a policy/human-review hold that changed the scanner's decision, or a genuine scan-explained hold such as a real scanner quarantine (`trigger_source`: `mailbox_policy` | `scanner` | `both`); it stays `None` on `sent`/terminal outcomes and normally on retryable infrastructure holds — a typed policy cause still attaches one (branch on `email_effect["effect_status"]` for those). `review_causes` is the typed hold-cause discriminator (`content_warning` | `first_contact` | `send_window` | `mailbox_policy`) driving a Supervised (`risky_only`) hold or a send-window promotion — a `NotRequired` key, absent on holds this dashboard policy builder didn't cause-type.
 
 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
@@ -361,10 +393,39 @@ rl.mailboxes.update(
 )
 ```
 
-Supported actions are `"allow"`, `"allow_with_warning"`, `"review"`, `"quarantine"`, and `"block"`. `"review"` routes matching sends to Pending approval; enabling it requires both Pro+ outbound PII controls and the review queue feature. Relaxing below platform defaults requires Pro+ (`pii_advanced_controls`); default or stricter values are accepted on every tier. Outbound PII scan results include `pii_type` (`"ssn"`, `"credit_card"`, or `"phone_number"`) so clients can inspect which type drove the action.
+Supported actions are `"allow"`, `"allow_with_warning"`, `"review"`, `"quarantine"`, and `"block"`. `"review"` routes matching sends to your review queue (approve/deny) — available on every tier. Relaxing below platform defaults requires Pro+ (`pii_advanced_controls`); default or stricter values are accepted on every tier. Outbound PII scan results include `pii_type` (`"ssn"`, `"credit_card"`, or `"phone_number"`) so clients can inspect which type drove the action.
 
 Approval notes are optional by default. Set `outbound_review_policy.approval_note` to `"required_for_sensitive_pii"` when approvers must add a note before sending SSN or credit-card review holds.
 
+### Mailbox policy fields (dashboard policy builder)
+
+`rl.mailboxes.update()` also accepts the per-mailbox fields the dashboard policy builder governs: `agent_authoring_mode` (`"send_and_draft"` | `"draft_only"` | `"read_only"`), `hitl_mode` (now widened to `"disabled"` | `"all_outbound"` | `"risky_only"`), `approval_expiry` (`"24h"` | `"72h"` | `"7d"` | `"never"`), and `send_window` (a dict binding AGENT-origin sends to a weekly window). `apply_policy_mode` applies one of the four named modes (`"read_only"` / `"draft_only"` / `"supervised"` / `"trusted"`) atomically and is mutually exclusive with those raw identity fields in the same call (the server returns `400 AMBIGUOUS_POLICY_MODE_APPLICATION`).
+
+```python
+# Apply a named mode — writes agent_authoring_mode/hitl_mode/agent_send_policy together.
+rl.mailboxes.update(mailbox["id"], apply_policy_mode="supervised")
+
+# Or set fields directly (not combined with apply_policy_mode in the same call).
+rl.mailboxes.update(
+    mailbox["id"],
+    agent_authoring_mode="draft_only",
+    approval_expiry="72h",
+    send_window={
+        "timezone": "America/Chicago",
+        "days": ["mon", "tue", "wed", "thu", "fri"],
+        "start": "09:00",
+        "end": "18:00",
+        "outside_action": "require_approval",
+    },
+)
+
+# send_window omitted (default) leaves it unchanged; pass send_window=None
+# explicitly to CLEAR it (always-open — a loosening).
+rl.mailboxes.update(mailbox["id"], send_window=None)
+```
+
+**Direction gate.** Tightening (toward `read_only`/shorter expiry/narrower window) works with an admin API key. Any loosening requires a dashboard session + fresh re-auth — a bearer key gets `403 REAUTH_REQUIRES_SESSION`. `rl.policy.get_mailbox_policy(mailbox_id)` reads the derived `policy_mode`, `last_applied_policy_mode`, the calling key's `binding["permitted_verbs"]`, and `enforcement` — the live rollout-lever state (`{"risky_only": ..., "send_window": ...}`, each `"off"` | `"shadow"` | `"enforce"`). A stored `hitl_mode="risky_only"` or `send_window` only actually holds a send when the matching `enforcement` field reads `"enforce"`; `off`/`shadow` mean the posture is saved but not yet active. `rl.policy.get_overview()` carries the same `enforcement` block once, account-wide (the levers are env-global, not per-mailbox). `rl.policy.preview_mailbox_policy(mailbox_id, to=...)` is a side-effect-free dry-run of the gate stack for a sample send.
+
 ### Agent Attachment Access
 
 Effective attachment exposure now comes from the mailbox policy surface (`attachment_exposure_mode` plus `attachment_allowed_file_families`), not from the legacy `attachment_access_enabled` boolean alone. Admin keys, pre-scoping keys, and dashboard sessions still bypass the agent mailbox-policy gate. Agent-key download requests without an explicit raw-download policy return 403 `ATTACHMENT_ACCESS_DISABLED` — surfaced as `ReplyLayerError` with `.code == "ATTACHMENT_ACCESS_DISABLED"`:
@@ -387,11 +448,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.
@@ -413,7 +474,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`.
+The same `RECIPIENT_SUPPRESSED` code also fires for a **platform-scoped** cross-account hard-bounce hit — an address that hard-bounced somewhere on the platform (not necessarily on your account), which ReplyLayer refuses on every ReplyLayer-managed sending domain to protect the shared reputation every customer rides on (never enforced on a delegated/BYOD or self-hosted domain). `details["scope"] == "platform"` distinguishes it from your own list (which omits `scope`); this variant isn't in `GET /v1/suppressions` and can't be removed via the SDK — it's an operator-only override.
+
+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
 
@@ -466,9 +529,42 @@ Webhook deliveries are deduped server-side to at most one per `(account, mailbox
 
 The MCP tool `list_allowlist_blocked_attempts` exposes the same view to agents — read-only by design. There is no dismiss-attempt tool (the containment boundary would be moot if an agent could clear its own rejection history).
 
+## Recipient verification (send-path safety checks)
+
+`POST /v1/messages/send`, `.../reply`, and `POST /v1/drafts/:id/send` run a permissive, fail-open recipient-quality check before dispatch. Only a **confirmed** violation rejects the send — an infrastructure hiccup (DNS blip, verification service outage) never blocks it. A reply or thread continuation is exempt (the recipient is a proven correspondent). Five `ReplyLayerError` codes, all HTTP 422:
+
+| Code | Meaning |
+|---|---|
+| `RECIPIENT_ADDRESS_INVALID` | The address fails a strict syntax check beyond the basic email-format validation. |
+| `RECIPIENT_DOMAIN_TYPO_SUSPECTED` | The domain looks like a single-character typo of a common consumer mail provider (e.g. `gmial.com`). The suggested domain rides in the exception message. |
+| `RECIPIENT_ROLE_ADDRESS` | The local part is a structural role/distribution mailbox (`noreply@`, `no-reply@`, etc. by default), not an individual inbox. |
+| `RECIPIENT_DISPOSABLE_ADDRESS` | The domain is a known disposable/temporary email provider. |
+| `RECIPIENT_UNDELIVERABLE` | The domain has no mail servers (no MX or A record) — mail to it would hard-bounce. |
+
+```python
+from replylayer import ValidationError
+
+try:
+    rl.messages.send(from_mailbox="support", to="noreply@example.com", subject="hi", body="x")
+except ValidationError as err:
+    if err.code == "RECIPIENT_ROLE_ADDRESS":
+        print("That looks like a role mailbox, not a person — double-check the recipient.")
+```
+
+## Mailbox creation & sending-domain provisioning
+
+On paid accounts (once the per-account sending-domain estate is enabled), `rl.mailboxes.create(...)` can race the account's sending-domain setup. There are no new SDK methods — two error codes flow through the existing error envelope:
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `DOMAIN_PROVISIONING_PENDING` | 409 | The account's sending domain is still being set up (or a domain change is in flight). Retryable — `err.details["retry_after"]` carries the suggested seconds. Poll `rl.domains.list()` for the platform row's `verification_status`. |
+| `DOMAIN_PROVISIONING_FAILED` | 409 | Sending-domain setup failed. Not retryable from the client — contact support. |
+
+The SDK deliberately does **not** auto-retry; retry loops live in the CLI (`rly mailbox create` waits up to 60s) and the dashboard.
+
 ## Malicious link scanning (URL reputation)
 
-Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). It is off by default and opt-in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
+Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). New accounts have it enabled by default at signup (disclosed in Privacy Policy §7a; per-mailbox opt-out via the mailbox scanner policy); older accounts opt in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
 
 Pass the version you are acknowledging explicitly; the SDK does not auto-fetch it, so the consent is recorded against a version your code chose:
 
@@ -481,7 +577,7 @@ if not status["active"] and status["privacy_ok"]:
     # res["url_reputation"]["active"] is True; res["disclosure"]["notice"] / ["advisory_url"]
 ```
 
-If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
+If `privacy_ok` is `False` the account's acknowledged privacy policy version predates the disclosed sub-processor — review and acknowledge 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
 
@@ -500,7 +596,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.
@@ -549,7 +645,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

{replylayer-0.22.1 → replylayer-0.26.0}/README.md

@@ -144,13 +144,45 @@ may no longer be available. The async client exposes the same methods.
 | `rl.recipients` | `create`, `list`, `delete`, `resend` |
 | `rl.suppressions` | `list`, `add`, `add_bulk`, `delete` |
 | `rl.inbound_blocklist` | `list`, `add`, `add_bulk`, `delete` |
-| `rl.api_keys` | `create`, `list`, `revoke`, `rotate`* |
+| `rl.api_keys` | `create`, `list`, `update`, `revoke`, `rotate`* |
 | `rl.account` | `get_usage`, `get_quota`, `get_link_scanning_status`, `enable_link_scanning`, `export` |
 | `rl.legal_holds` | `apply`, `release`, `list`, `get` |
 | `rl.health` | `check` |
+| `rl.simulator` | `inject_inbound` |
+| `rl.policy` | `get_mailbox_policy`, `get_overview`, `get_account_policy`, `update_account_policy`, `preview_mailbox_policy` |
 
 *`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.
 
+## Simulator
+
+Outbound scenarios use the normal send methods. Inbound scenarios use
+`rl.simulator.inject_inbound()`:
+
+```python
+outbound = rl.messages.send(
+    from_mailbox=mailbox["name"],
+    to="delivered+ci-run-42@simulator.replylayer.net",
+    subject="simulator check",
+    body="exercise the delivered path",
+)
+
+inbound = rl.simulator.inject_inbound({
+    "mailbox_id": mailbox["id"],
+    "scenario": "clean",
+    "label": "ci-run-42",
+})
+
+# Branch on the result: available | quarantined | pending.
+print(outbound["message_id"], inbound["status"], inbound.get("message_id"))
+```
+
+Outbound delivery, bounce, complaint, and suppression addresses; delayed webhook
+outcomes; inbound scenario semantics; and billing/suppression caveats are defined in
+the [email simulator guide](https://replylayer.ai/docs/guides/simulator).
+One Sandbox account can run all four exact outbound scenarios in the same day; those
+addresses bypass destination-concentration controls but still consume normal
+daily/cumulative usage allowance.
+
 ## Drafts: scan-then-review-then-send
 
 `rl.drafts.create()` runs the outbound scanner synchronously and attaches the verdict to the draft. The create-time verdict is UX — it lets an agent (or a human approver) see the likely outcome before clicking send. `rl.drafts.send()` **re-runs the scanner authoritatively** against the mailbox's current policy, so a stale cached verdict cannot slip through.
@@ -167,12 +199,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", "review_causes"?, "agent_instructions"}` or `None`) is the policy/human-review reason plus held-send guidance, non-None on held sends — a typed policy cause (first-contact/send-window/Supervised), a policy/human-review hold that changed the scanner's decision, or a genuine scan-explained hold such as a real scanner quarantine (`trigger_source`: `mailbox_policy` | `scanner` | `both`); it stays `None` on `sent`/terminal outcomes and normally on retryable infrastructure holds — a typed policy cause still attaches one (branch on `email_effect["effect_status"]` for those). `review_causes` is the typed hold-cause discriminator (`content_warning` | `first_contact` | `send_window` | `mailbox_policy`) driving a Supervised (`risky_only`) hold or a send-window promotion — a `NotRequired` key, absent on holds this dashboard policy builder didn't cause-type.
 
 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
@@ -341,10 +373,39 @@ rl.mailboxes.update(
 )
 ```
 
-Supported actions are `"allow"`, `"allow_with_warning"`, `"review"`, `"quarantine"`, and `"block"`. `"review"` routes matching sends to Pending approval; enabling it requires both Pro+ outbound PII controls and the review queue feature. Relaxing below platform defaults requires Pro+ (`pii_advanced_controls`); default or stricter values are accepted on every tier. Outbound PII scan results include `pii_type` (`"ssn"`, `"credit_card"`, or `"phone_number"`) so clients can inspect which type drove the action.
+Supported actions are `"allow"`, `"allow_with_warning"`, `"review"`, `"quarantine"`, and `"block"`. `"review"` routes matching sends to your review queue (approve/deny) — available on every tier. Relaxing below platform defaults requires Pro+ (`pii_advanced_controls`); default or stricter values are accepted on every tier. Outbound PII scan results include `pii_type` (`"ssn"`, `"credit_card"`, or `"phone_number"`) so clients can inspect which type drove the action.
 
 Approval notes are optional by default. Set `outbound_review_policy.approval_note` to `"required_for_sensitive_pii"` when approvers must add a note before sending SSN or credit-card review holds.
 
+### Mailbox policy fields (dashboard policy builder)
+
+`rl.mailboxes.update()` also accepts the per-mailbox fields the dashboard policy builder governs: `agent_authoring_mode` (`"send_and_draft"` | `"draft_only"` | `"read_only"`), `hitl_mode` (now widened to `"disabled"` | `"all_outbound"` | `"risky_only"`), `approval_expiry` (`"24h"` | `"72h"` | `"7d"` | `"never"`), and `send_window` (a dict binding AGENT-origin sends to a weekly window). `apply_policy_mode` applies one of the four named modes (`"read_only"` / `"draft_only"` / `"supervised"` / `"trusted"`) atomically and is mutually exclusive with those raw identity fields in the same call (the server returns `400 AMBIGUOUS_POLICY_MODE_APPLICATION`).
+
+```python
+# Apply a named mode — writes agent_authoring_mode/hitl_mode/agent_send_policy together.
+rl.mailboxes.update(mailbox["id"], apply_policy_mode="supervised")
+
+# Or set fields directly (not combined with apply_policy_mode in the same call).
+rl.mailboxes.update(
+    mailbox["id"],
+    agent_authoring_mode="draft_only",
+    approval_expiry="72h",
+    send_window={
+        "timezone": "America/Chicago",
+        "days": ["mon", "tue", "wed", "thu", "fri"],
+        "start": "09:00",
+        "end": "18:00",
+        "outside_action": "require_approval",
+    },
+)
+
+# send_window omitted (default) leaves it unchanged; pass send_window=None
+# explicitly to CLEAR it (always-open — a loosening).
+rl.mailboxes.update(mailbox["id"], send_window=None)
+```
+
+**Direction gate.** Tightening (toward `read_only`/shorter expiry/narrower window) works with an admin API key. Any loosening requires a dashboard session + fresh re-auth — a bearer key gets `403 REAUTH_REQUIRES_SESSION`. `rl.policy.get_mailbox_policy(mailbox_id)` reads the derived `policy_mode`, `last_applied_policy_mode`, the calling key's `binding["permitted_verbs"]`, and `enforcement` — the live rollout-lever state (`{"risky_only": ..., "send_window": ...}`, each `"off"` | `"shadow"` | `"enforce"`). A stored `hitl_mode="risky_only"` or `send_window` only actually holds a send when the matching `enforcement` field reads `"enforce"`; `off`/`shadow` mean the posture is saved but not yet active. `rl.policy.get_overview()` carries the same `enforcement` block once, account-wide (the levers are env-global, not per-mailbox). `rl.policy.preview_mailbox_policy(mailbox_id, to=...)` is a side-effect-free dry-run of the gate stack for a sample send.
+
 ### Agent Attachment Access
 
 Effective attachment exposure now comes from the mailbox policy surface (`attachment_exposure_mode` plus `attachment_allowed_file_families`), not from the legacy `attachment_access_enabled` boolean alone. Admin keys, pre-scoping keys, and dashboard sessions still bypass the agent mailbox-policy gate. Agent-key download requests without an explicit raw-download policy return 403 `ATTACHMENT_ACCESS_DISABLED` — surfaced as `ReplyLayerError` with `.code == "ATTACHMENT_ACCESS_DISABLED"`:
@@ -367,11 +428,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.
@@ -393,7 +454,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`.
+The same `RECIPIENT_SUPPRESSED` code also fires for a **platform-scoped** cross-account hard-bounce hit — an address that hard-bounced somewhere on the platform (not necessarily on your account), which ReplyLayer refuses on every ReplyLayer-managed sending domain to protect the shared reputation every customer rides on (never enforced on a delegated/BYOD or self-hosted domain). `details["scope"] == "platform"` distinguishes it from your own list (which omits `scope`); this variant isn't in `GET /v1/suppressions` and can't be removed via the SDK — it's an operator-only override.
+
+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
 
@@ -446,9 +509,42 @@ Webhook deliveries are deduped server-side to at most one per `(account, mailbox
 
 The MCP tool `list_allowlist_blocked_attempts` exposes the same view to agents — read-only by design. There is no dismiss-attempt tool (the containment boundary would be moot if an agent could clear its own rejection history).
 
+## Recipient verification (send-path safety checks)
+
+`POST /v1/messages/send`, `.../reply`, and `POST /v1/drafts/:id/send` run a permissive, fail-open recipient-quality check before dispatch. Only a **confirmed** violation rejects the send — an infrastructure hiccup (DNS blip, verification service outage) never blocks it. A reply or thread continuation is exempt (the recipient is a proven correspondent). Five `ReplyLayerError` codes, all HTTP 422:
+
+| Code | Meaning |
+|---|---|
+| `RECIPIENT_ADDRESS_INVALID` | The address fails a strict syntax check beyond the basic email-format validation. |
+| `RECIPIENT_DOMAIN_TYPO_SUSPECTED` | The domain looks like a single-character typo of a common consumer mail provider (e.g. `gmial.com`). The suggested domain rides in the exception message. |
+| `RECIPIENT_ROLE_ADDRESS` | The local part is a structural role/distribution mailbox (`noreply@`, `no-reply@`, etc. by default), not an individual inbox. |
+| `RECIPIENT_DISPOSABLE_ADDRESS` | The domain is a known disposable/temporary email provider. |
+| `RECIPIENT_UNDELIVERABLE` | The domain has no mail servers (no MX or A record) — mail to it would hard-bounce. |
+
+```python
+from replylayer import ValidationError
+
+try:
+    rl.messages.send(from_mailbox="support", to="noreply@example.com", subject="hi", body="x")
+except ValidationError as err:
+    if err.code == "RECIPIENT_ROLE_ADDRESS":
+        print("That looks like a role mailbox, not a person — double-check the recipient.")
+```
+
+## Mailbox creation & sending-domain provisioning
+
+On paid accounts (once the per-account sending-domain estate is enabled), `rl.mailboxes.create(...)` can race the account's sending-domain setup. There are no new SDK methods — two error codes flow through the existing error envelope:
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `DOMAIN_PROVISIONING_PENDING` | 409 | The account's sending domain is still being set up (or a domain change is in flight). Retryable — `err.details["retry_after"]` carries the suggested seconds. Poll `rl.domains.list()` for the platform row's `verification_status`. |
+| `DOMAIN_PROVISIONING_FAILED` | 409 | Sending-domain setup failed. Not retryable from the client — contact support. |
+
+The SDK deliberately does **not** auto-retry; retry loops live in the CLI (`rly mailbox create` waits up to 60s) and the dashboard.
+
 ## Malicious link scanning (URL reputation)
 
-Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). It is off by default and opt-in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
+Malicious link scanning checks inbound links against Google Web Risk (only SHA-256 hash-prefixes are sent — full URLs never leave the platform). New accounts have it enabled by default at signup (disclosed in Privacy Policy §7a; per-mailbox opt-out via the mailbox scanner policy); older accounts opt in per account. Enabling it is an **admin action** (it turns on an account-wide sub-processor data flow), so agent-scoped keys can read status but not enable it (they raise `ForbiddenError`).
 
 Pass the version you are acknowledging explicitly; the SDK does not auto-fetch it, so the consent is recorded against a version your code chose:
 
@@ -461,7 +557,7 @@ if not status["active"] and status["privacy_ok"]:
     # res["url_reputation"]["active"] is True; res["disclosure"]["notice"] / ["advisory_url"]
 ```
 
-If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
+If `privacy_ok` is `False` the account's acknowledged privacy policy version predates the disclosed sub-processor — review and acknowledge 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
 
@@ -480,7 +576,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.
@@ -529,7 +625,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

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

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

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

@@ -90,6 +90,9 @@ from .types import (
     MessageReviewQueuedWebhookPayload,
     MessageReviewApprovedWebhookPayload,
     MessageReviewDeniedWebhookPayload,
+    # Policy builder slice 3b / §7 — expiry + release webhook payloads.
+    MessageReviewExpiredWebhookPayload,
+    MessageReleasedWebhookPayload,
     # PR 7 — scanner-emit HITL review surface.
     ReviewQueueTriggerSource,
     # PR 9 — outbound PII safety tuning.
@@ -99,9 +102,25 @@ from .types import (
     OutboundReviewApprovalNotePolicy,
     OutboundReviewPolicy,
     ScannerPolicy,
+    # First-party simulator MVP (plans/replylayer-simulator-mvp.md).
+    InjectSimulatorInboundRequest,
+    InjectSimulatorInboundResponse,
+    # Dashboard policy builder (plans/dashboard-policy-builder-mvp-2026-07-07.md §6.1).
+    PolicyMode,
+    DefaultPolicyMode,
+    AgentAuthoringMode,
+    MailboxHitlMode,
+    ApprovalExpiry,
+    AgentAuthoringVerb,
+    SendWindow,
+    PolicyEnforcement,
+    MailboxPolicy,
+    AccountPolicy,
+    PolicyOverview,
+    PolicyPreviewResult,
 )
 
-__version__ = "0.22.1"
+__version__ = "0.26.0"
 
 __all__ = [
     # Message delete response (0.20.0).
@@ -188,6 +207,8 @@ __all__ = [
     "MessageReviewQueuedWebhookPayload",
     "MessageReviewApprovedWebhookPayload",
     "MessageReviewDeniedWebhookPayload",
+    "MessageReviewExpiredWebhookPayload",
+    "MessageReleasedWebhookPayload",
     # PR 7 — scanner-emit HITL.
     "ReviewQueueTriggerSource",
     # PR 9 — outbound PII safety tuning.
@@ -197,5 +218,21 @@ __all__ = [
     "OutboundReviewApprovalNotePolicy",
     "OutboundReviewPolicy",
     "ScannerPolicy",
+    # First-party simulator MVP.
+    "InjectSimulatorInboundRequest",
+    "InjectSimulatorInboundResponse",
+    # Dashboard policy builder (§6.1).
+    "PolicyMode",
+    "DefaultPolicyMode",
+    "AgentAuthoringMode",
+    "MailboxHitlMode",
+    "ApprovalExpiry",
+    "AgentAuthoringVerb",
+    "SendWindow",
+    "PolicyEnforcement",
+    "MailboxPolicy",
+    "AccountPolicy",
+    "PolicyOverview",
+    "PolicyPreviewResult",
     "__version__",
 ]

{replylayer-0.22.1 → replylayer-0.26.0}/replylayer/_client.py

@@ -22,6 +22,8 @@ from .resources.account import SyncAccount, AsyncAccount
 from .resources.health import SyncHealth, AsyncHealth
 from .resources.domains import SyncDomains, AsyncDomains
 from .resources.legal_holds import SyncLegalHolds, AsyncLegalHolds
+from .resources.simulator import SyncSimulator, AsyncSimulator
+from .resources.policy import SyncPolicy, AsyncPolicy
 
 _DEFAULT_BASE_URL = "https://api.replylayer.ai"
 
@@ -74,6 +76,8 @@ class ReplyLayer:
         self.account = SyncAccount(self._http)
         self.health = SyncHealth(self._http)
         self.legal_holds = SyncLegalHolds(self._http)
+        self.simulator = SyncSimulator(self._http)
+        self.policy = SyncPolicy(self._http)
 
     def close(self) -> None:
         self._http.close()
@@ -128,6 +132,8 @@ class AsyncReplyLayer:
         self.account = AsyncAccount(self._http)
         self.health = AsyncHealth(self._http)
         self.legal_holds = AsyncLegalHolds(self._http)
+        self.simulator = AsyncSimulator(self._http)
+        self.policy = AsyncPolicy(self._http)
 
     async def aclose(self) -> None:
         await self._http.aclose()

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

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

{replylayer-0.22.1 → replylayer-0.26.0}/replylayer/resources/api_keys.py

@@ -23,6 +23,14 @@ class SyncApiKeys:
         query = {"include_revoked": "true"} if include_revoked else None
         return self._http.request("GET", "/v1/accounts/api-keys", query=query)
 
+    def update(self, id: str, *, mailbox_ids: list[str]) -> dict[str, Any]:
+        """Update an agent key's mailbox bindings in place (full replace). The
+        key's secret and per-key capabilities are untouched; the change takes
+        effect on the key's next request. Admin-only; agent keys cannot re-scope."""
+        return self._http.request(
+            "PATCH", f"/v1/accounts/api-keys/{id}", body={"mailbox_ids": mailbox_ids}
+        )
+
     def revoke(self, id: str) -> dict[str, Any]:
         return self._http.request("DELETE", f"/v1/accounts/api-keys/{id}")
 
@@ -50,6 +58,14 @@ class AsyncApiKeys:
         query = {"include_revoked": "true"} if include_revoked else None
         return await self._http.request("GET", "/v1/accounts/api-keys", query=query)
 
+    async def update(self, id: str, *, mailbox_ids: list[str]) -> dict[str, Any]:
+        """Update an agent key's mailbox bindings in place (full replace). The
+        key's secret and per-key capabilities are untouched; the change takes
+        effect on the key's next request. Admin-only; agent keys cannot re-scope."""
+        return await self._http.request(
+            "PATCH", f"/v1/accounts/api-keys/{id}", body={"mailbox_ids": mailbox_ids}
+        )
+
     async def revoke(self, id: str) -> dict[str, Any]:
         return await self._http.request("DELETE", f"/v1/accounts/api-keys/{id}")
 

{replylayer-0.22.1 → replylayer-0.26.0}/replylayer/resources/drafts.py

@@ -209,7 +209,12 @@ class SyncDrafts:
         otherwise ``SendMessageResponse``. Attachment-bearing drafts fail
         closed on the async path (``400 ATTACHMENTS_REQUIRE_SYNC_SEND``).
         Poll ``messages.get(message_id)`` until ``state`` is terminal to
-        observe the final outcome.
+        observe the final outcome. On a sandbox account an
+        ``async_dispatch=True`` send can also raise a synchronous 409
+        ``DRAFT_REJECTED_BY_RESCAN`` *before* the 202 — the verified-recipients
+        gate (``recipient-check``) runs at the enqueue preflight, so an
+        unverified recipient is rejected up front, exactly as on the
+        synchronous path.
 
         Sandbox accounts are subject to a 250-cumulative-send trial
         budget. Once exhausted the API returns 403 with
@@ -359,7 +364,10 @@ class AsyncDrafts:
         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 ``status == "queued_for_dispatch"`` to distinguish the two.
+        branch on ``status == "queued_for_dispatch"`` to distinguish the two. A
+        sandbox unverified-recipient send can also raise a synchronous 409
+        ``DRAFT_REJECTED_BY_RESCAN`` before the 202 (the ``recipient-check``
+        enqueue preflight).
         """
         extra_headers: dict[str, str] | None = {"Prefer": "respond-async"} if async_dispatch else None
         return await self._http.request("POST", f"/v1/drafts/{id}/send", body={}, extra_headers=extra_headers)