replylayer 0.23.0__tar.gz → 0.27.0__tar.gz

{replylayer-0.23.0 → replylayer-0.27.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.23.0 → replylayer-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: replylayer
-Version: 0.23.0
+Version: 0.27.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,7 +219,7 @@ 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/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`).
+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.)
 
@@ -244,6 +276,34 @@ result = rl.messages.send(
 
 A handle is **consumed once** at send and is single-mailbox-scoped (upload to the same mailbox you send from). Unconsumed handles expire after 24h; delete one early with `rl.attachments.delete_upload(handle["id"])`. Limits: 10 MB/file, 10 attachments and 15 MB total per message. Image attachments require a separate one-time image-risk disclaimer on the mailbox (`OUTBOUND_IMAGE_DISCLAIMER_REQUIRED`). Drafts hold handles and consume them at dispatch; `rl.drafts.update(draft_id, attachment_ids=None)` clears a draft's attachments. Attachment bytes are stored with provider-managed encryption-at-rest and transmitted over TLS — this is not end-to-end / zero-access encryption (the platform scans attachment content).
 
+## Webhook custom request headers
+
+For a receiver that authenticates by a fixed header rather than by ReplyLayer's HMAC, `webhooks.create` and `webhooks.update` accept `request_headers` — up to 8 static headers added to every delivery attempt for that webhook (first attempt, every retry, `test()`, and a manual `retry_delivery`).
+
+```python
+wh = rl.webhooks.create(
+    url="https://your-server.com/hooks/replylayer",
+    enabled_events=["message.received"],
+    request_headers={"Authorization": "Bearer your-receiver-token"},
+)
+
+wh["request_header_names"]  # ['authorization'] — names only, lower-cased + sorted
+```
+
+**Values are write-only.** They are encrypted at rest and returned by no read path: every webhook response carries `request_header_names` (`[]` when none) and never a value. Because of that, `update` is three-way and there is no per-header merge:
+
+```python
+rl.webhooks.update(wh["id"], request_headers={"Authorization": "Bearer rotated"})  # replaces the whole map
+rl.webhooks.update(wh["id"], request_headers=None)                                # clears every header
+rl.webhooks.update(wh["id"], enabled=False)                                       # leaves headers untouched
+```
+
+`None` means "clear" here, so omitting the argument entirely is the only way to leave the configured headers alone.
+
+Names match `^[A-Za-z0-9-]{1,64}$` and are compared case-insensitively; values are 1–1024 printable-ASCII characters. Reserved names — `content-type`, `content-length`, `host`, `user-agent`, `x-replylayer-signature`, `x-webhook-timestamp`, `x-webhook-signature-v2`, `transfer-encoding`, `connection`, `expect`, `te`, `upgrade`, `keep-alive`, `trailer`, and anything starting with `proxy-` — are rejected. The SDK does not pre-validate: rejections arrive as `ReplyLayerError` with `.code` set to `WEBHOOK_HEADER_RESERVED`, `WEBHOOK_HEADER_DUPLICATE`, `WEBHOOK_HEADER_INVALID`, or `VALIDATION_ERROR`.
+
+Deliveries for a webhook with custom headers store no response body (`response_preview` is always `None`), so a receiver that echoes the request cannot leak a configured credential back into the delivery history.
+
 ## Delivery history & manual retry
 
 `rl.webhooks.list_deliveries(id, limit=..., before_at=..., before_id=...)` returns the most recent delivery attempts for a webhook with tuple-cursor keyset pagination. `before_at` and `before_id` must be provided together — the SDK omits the cursor entirely if only one is given.
@@ -361,10 +421,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"`:
@@ -413,6 +502,8 @@ 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.
 
+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 +557,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 +605,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
 

{replylayer-0.23.0 → replylayer-0.27.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,7 +199,7 @@ 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/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`).
+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.)
 
@@ -224,6 +256,34 @@ result = rl.messages.send(
 
 A handle is **consumed once** at send and is single-mailbox-scoped (upload to the same mailbox you send from). Unconsumed handles expire after 24h; delete one early with `rl.attachments.delete_upload(handle["id"])`. Limits: 10 MB/file, 10 attachments and 15 MB total per message. Image attachments require a separate one-time image-risk disclaimer on the mailbox (`OUTBOUND_IMAGE_DISCLAIMER_REQUIRED`). Drafts hold handles and consume them at dispatch; `rl.drafts.update(draft_id, attachment_ids=None)` clears a draft's attachments. Attachment bytes are stored with provider-managed encryption-at-rest and transmitted over TLS — this is not end-to-end / zero-access encryption (the platform scans attachment content).
 
+## Webhook custom request headers
+
+For a receiver that authenticates by a fixed header rather than by ReplyLayer's HMAC, `webhooks.create` and `webhooks.update` accept `request_headers` — up to 8 static headers added to every delivery attempt for that webhook (first attempt, every retry, `test()`, and a manual `retry_delivery`).
+
+```python
+wh = rl.webhooks.create(
+    url="https://your-server.com/hooks/replylayer",
+    enabled_events=["message.received"],
+    request_headers={"Authorization": "Bearer your-receiver-token"},
+)
+
+wh["request_header_names"]  # ['authorization'] — names only, lower-cased + sorted
+```
+
+**Values are write-only.** They are encrypted at rest and returned by no read path: every webhook response carries `request_header_names` (`[]` when none) and never a value. Because of that, `update` is three-way and there is no per-header merge:
+
+```python
+rl.webhooks.update(wh["id"], request_headers={"Authorization": "Bearer rotated"})  # replaces the whole map
+rl.webhooks.update(wh["id"], request_headers=None)                                # clears every header
+rl.webhooks.update(wh["id"], enabled=False)                                       # leaves headers untouched
+```
+
+`None` means "clear" here, so omitting the argument entirely is the only way to leave the configured headers alone.
+
+Names match `^[A-Za-z0-9-]{1,64}$` and are compared case-insensitively; values are 1–1024 printable-ASCII characters. Reserved names — `content-type`, `content-length`, `host`, `user-agent`, `x-replylayer-signature`, `x-webhook-timestamp`, `x-webhook-signature-v2`, `transfer-encoding`, `connection`, `expect`, `te`, `upgrade`, `keep-alive`, `trailer`, and anything starting with `proxy-` — are rejected. The SDK does not pre-validate: rejections arrive as `ReplyLayerError` with `.code` set to `WEBHOOK_HEADER_RESERVED`, `WEBHOOK_HEADER_DUPLICATE`, `WEBHOOK_HEADER_INVALID`, or `VALIDATION_ERROR`.
+
+Deliveries for a webhook with custom headers store no response body (`response_preview` is always `None`), so a receiver that echoes the request cannot leak a configured credential back into the delivery history.
+
 ## Delivery history & manual retry
 
 `rl.webhooks.list_deliveries(id, limit=..., before_at=..., before_id=...)` returns the most recent delivery attempts for a webhook with tuple-cursor keyset pagination. `before_at` and `before_id` must be provided together — the SDK omits the cursor entirely if only one is given.
@@ -341,10 +401,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"`:
@@ -393,6 +482,8 @@ 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.
 
+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 +537,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 +585,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
 

{replylayer-0.23.0 → replylayer-0.27.0}/pyproject.toml

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

{replylayer-0.23.0 → replylayer-0.27.0}/replylayer/__init__.py

@@ -29,6 +29,8 @@ from .types import (
     # WS6-SDK — async optimistic-ack (0.16.0).
     AsyncSendAck,
     WebhookEventType,
+    # Migration 134 — per-webhook custom request headers (write-only values).
+    WebhookRequestHeaders,
     WebhookSummary,
     WebhookDeliverySummary,
     WebhookDeliveryStatus,
@@ -90,6 +92,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 +104,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.23.0"
+__version__ = "0.27.0"
 
 __all__ = [
     # Message delete response (0.20.0).
@@ -136,6 +157,8 @@ __all__ = [
     "EmailEffect",
     "EffectStatus",
     "WebhookEventType",
+    # Migration 134 — per-webhook custom request headers (write-only values).
+    "WebhookRequestHeaders",
     "WebhookSummary",
     "WebhookDeliverySummary",
     "WebhookDeliveryStatus",
@@ -188,6 +211,8 @@ __all__ = [
     "MessageReviewQueuedWebhookPayload",
     "MessageReviewApprovedWebhookPayload",
     "MessageReviewDeniedWebhookPayload",
+    "MessageReviewExpiredWebhookPayload",
+    "MessageReleasedWebhookPayload",
     # PR 7 — scanner-emit HITL.
     "ReviewQueueTriggerSource",
     # PR 9 — outbound PII safety tuning.
@@ -197,5 +222,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.23.0 → replylayer-0.27.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.23.0 → replylayer-0.27.0}/replylayer/_http.py

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

{replylayer-0.23.0 → replylayer-0.27.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.23.0 → replylayer-0.27.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)