replylayer 0.14.0__py3-none-any.whl

replylayer/types.py

@@ -0,0 +1,1578 @@
+"""SDK types — self-contained for PyPI publishing.
+
+Derived from packages/sdk/src/types.ts — keep in sync.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, TypedDict, Union
+# Required/NotRequired land in `typing` proper at 3.11; package targets 3.10
+# (per pyproject.toml requires-python). typing_extensions backports them.
+from typing_extensions import Required, NotRequired
+
+# === Enums (Literal unions) ===
+
+MessageDirection = Literal["inbound", "outbound"]
+MessageState = Literal[
+    "draft", "received", "scanning", "available", "quarantined",
+    # Migration 059 / PR 6 — HITL review queue (Pro+); non-terminal
+    # (approve→'available', deny→'blocked').
+    "pending_review",
+    "blocked", "delivered", "bounced", "deleted",
+    # Migration 047 — inbound firewall verdict; non-terminal (releasable to scanning).
+    "firewall_blocked",
+]
+MailboxStatus = Literal["active", "paused", "deleted"]
+RecipientStatus = Literal["pending", "confirmed", "expired"]
+SuppressionReason = Literal["hard_bounce", "complaint", "manual", "unsubscribe"]
+PolicyDecision = Literal[
+    "allow", "allow_with_warning", "quarantine",
+    "require_human_approval", "block",
+]
+AttachmentPolicyAction = Literal["deliver", "metadata_only", "quarantine", "block"]
+AvVerdict = Literal["clean", "infected", "error", "skipped"]
+AttachmentExposureMode = Literal["metadata_only", "derived_content", "raw_download_selected_types"]
+AttachmentAllowedFileFamily = Literal["pdf", "text", "csv", "image", "*"]
+AttachmentAllowedFileFamilyRequest = Literal["pdf", "text", "csv", "image"]
+AttachmentDerivativeVariant = Literal["preview_text"]
+AttachmentDerivativeStatus = Literal["pending", "ready", "blocked", "failed"]
+AttachmentPreviewKind = Literal["text"]
+AttachmentRawRetentionStatus = Literal[
+    "not_retained",
+    "temporary_processing",
+    "retained_for_raw_download",
+]
+WebhookEventType = Literal[
+    "message.received", "message.delivered", "message.bounced",
+    "message.quarantined", "message.scanner_blocked",
+    "attachment.preview.queued", "attachment.preview.ready",
+    "attachment.preview.blocked", "attachment.preview.failed",
+    # Migration 051 — vocabulary alignment: was suppression.* / allowlist.*;
+    # renamed to recipient_blocklist.* / recipient_allowlist.* to mirror
+    # the inbound side. recipient_blocklist.complaint_override is new.
+    "recipient_blocklist.added", "recipient_blocklist.removed",
+    "recipient_blocklist.complaint_override",
+    "recipient_allowlist.added", "recipient_allowlist.removed",
+    "mailbox.recipient_policy_changed",
+    "recipient_allowlist.blocked_attempt",
+    # Migration 040 — scheduled-send lifecycle events.
+    "message.scheduled", "message.rescheduled",
+    "message.schedule_cancelled", "message.dispatch_failed",
+    # Migration 047 — inbound firewall events.
+    "inbound_sender.blocked",
+    "sender_allowlist.added", "sender_allowlist.removed",
+    "sender_blocklist.added", "sender_blocklist.removed",
+    "mailbox.sender_policy_changed",
+    # PR 3 — customer legal hold lifecycle (Pro+ apply; release available
+    # on every plan, so subscribing to .released stays useful post-downgrade).
+    "legal_hold.applied", "legal_hold.released",
+    # PR 6 — HITL review queue. queued fires post-commit when a message
+    # routes to state='pending_review'; approved/denied fire when the
+    # matching endpoint commits the state transition. Subscribable via
+    # POST/PATCH /v1/webhooks.enabled_events.
+    "message.review.queued", "message.review.approved", "message.review.denied",
+    "webhook.test",
+]
+ApiKeyRole = Literal["admin", "agent"]
+PiiMode = Literal["passthrough", "redacted"]
+OutboundPiiType = Literal["ssn", "credit_card", "phone_number"]
+OutboundPiiAction = Literal["allow", "allow_with_warning", "review", "quarantine", "block"]
+OutboundPiiPolicy = dict[OutboundPiiType, OutboundPiiAction]
+OutboundReviewApprovalNotePolicy = Literal["optional", "required_for_sensitive_pii"]
+
+
+class OutboundReviewPolicy(TypedDict, total=False):
+    approval_note: OutboundReviewApprovalNotePolicy
+
+
+# PR 8.2 — per-detector redaction operator kinds.
+#   - replace_with_type (default): replaces the span with <TYPE>.
+#   - partial_mask: masks alphanumerics from the LEFT, keeps last
+#     keep_last (1-6), preserves separators verbatim. Pro+ gated;
+#     whitelisted detectors only (PERSON/EMAIL_ADDRESS rejected).
+#   - hash_replace: replaces span with <TYPE:hash> using HMAC-SHA256
+#     with the per-account salt. Pro+ gated.
+PiiOperatorKind = Literal["replace_with_type", "partial_mask", "hash_replace"]
+
+
+# Operator config for replace_with_type — the explicit default. Carries
+# only the discriminator. Validator rejects keep_last/mask_char on this
+# kind (round-3 audit fix #4 — prevents dead config persisting).
+class PiiReplaceWithTypeOperator(TypedDict):
+    kind: Literal["replace_with_type"]
+
+
+# Operator config for partial_mask. keep_last is REQUIRED integer in
+# [1, 6]; mask_char is OPTIONAL single character (defaults to '*' when
+# omitted). Validator rejects partial_mask on PERSON / EMAIL_ADDRESS
+# (briefing §6.1 whitelist) — partial-masking a name produces nonsense
+# and partial-masking an email is hard to do well in v1.
+class PiiPartialMaskOperator(TypedDict, total=False):
+    kind: Required[Literal["partial_mask"]]
+    keep_last: Required[int]
+    mask_char: str  # NotRequired by virtue of total=False
+
+
+# Operator config for hash_replace — replaces the span with
+# <TYPE:HMAC-SHA256(account_salt, span)[0..8]>. No per-detector config
+# in v1; the per-account salt lives on accounts.pii_hash_salt and is
+# lazy-initialized by the mailbox PATCH route on first hash_replace use.
+# Validator rejects keep_last/mask_char on this kind (round-3 audit fix #4).
+class PiiHashReplaceOperator(TypedDict):
+    kind: Literal["hash_replace"]
+
+
+# PR 8.2 — per-detector redaction operator. Concrete Union over the three
+# kinds gives static type-checkers a real contract to verify (mirrors the
+# TS SDK's discriminated union). Round-1 PR 8.2 audit fix #1: prior shape
+# was `Dict[str, Any]` which collapsed to no static guarantee — invalid
+# configs like {"kind": "hash_replace", "keep_last": 4} would slip past
+# typing despite the server's 422 rejection.
+PiiOperator = Union[
+    PiiReplaceWithTypeOperator,
+    PiiPartialMaskOperator,
+    PiiHashReplaceOperator,
+]
+
+
+# PR 8.1 — per-detector redaction visibility entry. NULL/absent = platform
+# default (redact at delivery with `<TYPE>` placeholder). PR 8.2 adds the
+# optional `operator` field.
+class PiiRedactionConfigEntry(TypedDict, total=False):
+    redact: Required[bool]
+    operator: PiiOperator
+
+
+# PR 8.1 — partial map keyed by detector type (e.g. `EMAIL_ADDRESS`,
+# `CREDIT_CARD`). Persisted to `mailboxes.pii_redaction_config`. Omitted
+# keys default to platform behaviour (redacted).
+PiiRedactionConfig = Dict[str, PiiRedactionConfigEntry]
+
+# Per-send / per-mailbox sub-addressing mode (migration 035).
+#   - reply_to (default): only Reply-To is rewritten to
+#     mailbox+instance_id@domain. From stays clean.
+#   - from: also rewrites From to the subaddressed form.
+#   - none: no address rewrite. HMAC secure-reply headers are still
+#     injected when an instance_id is passed on the send.
+SubaddressMode = Literal["reply_to", "from", "none"]
+
+# Per-mailbox recipient policy mode (migration 036).
+#   - blocklist (default): suppressed_addresses is the only pre-send gate.
+#   - allowlist: recipient MUST be on recipient_allowlists for this mailbox
+#     or the send is rejected with 403 RECIPIENT_NOT_ON_ALLOWLIST. Blocklist
+#     still runs first (wins on overlap).
+RecipientPolicyMode = Literal["blocklist", "allowlist"]
+
+# Per-mailbox INBOUND sender firewall mode (migration 047). Symmetric
+# counterpart to RecipientPolicyMode for the inbound side.
+#   - blocklist (default): inbound_sender_blocklists is the only ingest gate.
+#   - allowlist: incoming sender MUST be on inbound_sender_allowlists for
+#     this mailbox or the message lands in state='firewall_blocked'.
+#     Blocklist still runs first (wins on overlap).
+# HMAC-verified agent replies bypass on both Mailgun and IMAP ingress.
+SenderPolicyMode = Literal["blocklist", "allowlist"]
+
+
+class FirewallBlock(TypedDict):
+    """Snapshot of the inbound firewall verdict that landed a message in
+    state='firewall_blocked' (migration 047). Surfaced on message read APIs
+    only when the row was firewall-blocked. Sender-PII fields
+    (envelope_sender, from_address, matched_pattern) are redacted by the
+    server when mailboxes.pii_mode='redacted'. Categorical fields pass through.
+    """
+
+    envelope_sender: str | None
+    from_address: str | None
+    matched_field: Literal["envelope", "from"] | None
+    matched_pattern: str | None
+    reason_code: Literal["SENDER_BLOCKED", "SENDER_NOT_ON_ALLOWLIST"]
+    source_table: Literal["inbound_sender_blocklists", "inbound_sender_allowlists"] | None
+    mode: SenderPolicyMode
+
+# Sprint 039 — allowlist + suppression entries may be either an exact email
+# (`alice@corp.com`) or a domain pattern (`@corp.com`). Server derives
+# `pattern_type` from the stored string. Optional on the wire (older server
+# versions omit it) so clients targeting pre-0.5.0 servers still typecheck.
+RecipientPatternType = Literal["email", "domain"]
+
+
+class _HasPatternType(TypedDict, total=False):
+    """Mixin: `pattern_type` is present on 0.5.0+ server responses, absent on
+    older servers. Inherited by every list/add/bulk-added/delete entry that
+    can now carry a domain pattern."""
+
+    pattern_type: RecipientPatternType
+
+# === Pagination ===
+
+@dataclass
+class Page:
+    data: list[dict[str, Any]]
+    has_more: bool
+    cursor: str | None
+
+
+# === Domains ===
+
+DomainType = Literal["platform", "delegated"]
+DomainVerificationStatus = Literal[
+    "pending", "verified", "failed",
+    "requested", "pending_dns", "provider_verified",
+    "pending_verification", "unhealthy", "rejected",
+]
+TransportMode = Literal["mailgun", "ses", "self_hosted"]
+AdminReviewStatus = Literal["pending_review", "approved", "rejected"]
+SelfHostedSecurity = Literal["starttls", "tls"]
+SelfHostedNetworkMode = Literal["public", "tailnet"]
+SelfHostedProbeGate = Literal["ownership_txt", "imap_auth", "smtp_auth", "folder_missing"]
+
+
+class SelfHostedEndpointConfig(TypedDict):
+    host: str
+    port: int
+    security: SelfHostedSecurity
+    username: str
+    password: str
+
+
+class SelfHostedConfig(TypedDict):
+    smtp: SelfHostedEndpointConfig
+    imap: SelfHostedEndpointConfig
+    network_mode: SelfHostedNetworkMode
+
+
+class SelfHostedProbeResult(TypedDict):
+    gate: SelfHostedProbeGate
+    ok: bool
+    error: str | None
+
+
+class DnsRecord(TypedDict, total=False):
+    type: Literal["TXT", "CNAME", "MX"]
+    name: str
+    value: str
+    priority: int
+    purpose: Literal["ownership_proof", "spf", "dkim", "tracking", "inbound_mx", "dmarc"]
+    mailgun_valid: bool | None
+
+
+class Domain(TypedDict, total=False):
+    id: str
+    domain_name: str
+    domain_type: DomainType
+    transport_mode: TransportMode
+    is_default: bool
+    verification_status: DomainVerificationStatus
+    dns_records_json: list[DnsRecord] | None
+    admin_review_status: AdminReviewStatus | None
+    suspended_at: str | None
+    created_at: str
+    verified_at: str | None
+    account_id: str
+    mailgun_domain_id: str | None
+    ses_verified: bool
+    claim_token: str | None
+    mailgun_route_id: str | None
+    https_tracking_enabled_at: str | None
+    admin_review_note: str | None
+    admin_reviewed_at: str | None
+    last_health_check_at: str | None
+    health_failure_count: int
+    suspended_by: str | None
+    suspension_reason: str | None
+    updated_at: str
+
+
+class CreateDomainRequest(TypedDict, total=False):
+    domain: str
+    transport_mode: TransportMode
+    self_hosted_config: SelfHostedConfig
+
+
+class UpdateSelfHostedDomainConfigRequest(TypedDict, total=False):
+    smtp: dict[str, Any]
+    imap: dict[str, Any]
+    network_mode: SelfHostedNetworkMode
+    tailnet_auth_key: str
+
+
+class CreateDomainResponse(TypedDict, total=False):
+    id: str
+    domain_id: str
+    domain_name: str
+    domain_type: DomainType
+    transport_mode: TransportMode
+    verification_status: DomainVerificationStatus
+    dns_records_json: list[DnsRecord] | None
+    admin_review_status: AdminReviewStatus | None
+    is_default: bool
+    created_at: str
+    message: str
+    claim_token: str | None
+
+
+class ListDomainsResponse(TypedDict):
+    domains: list[Domain]
+
+
+class VerifyDomainResponse(TypedDict, total=False):
+    verification_status: DomainVerificationStatus
+    dns_records_json: list[DnsRecord] | None
+    probe_results: list[SelfHostedProbeResult]
+    failed_gate: SelfHostedProbeGate | None
+    failure_reason: str | None
+    message: str
+
+
+class SelfHostedConfigResponse(TypedDict):
+    domain_id: str
+    network_mode: SelfHostedNetworkMode
+    smtp: dict[str, Any]
+    imap: dict[str, Any]
+    updated_at: str
+
+
+class DeleteDomainResponse(TypedDict):
+    deleted: bool
+
+
+class SetDefaultDomainResponse(TypedDict):
+    id: str
+    domain_name: str
+    is_default: bool
+
+
+# === Mailboxes ===
+
+# PR 6 — per-mailbox HITL trigger (migration 059). Defined before
+# CreateMailboxResponse / Mailbox / UpdateMailboxResponse / UpdateMailboxRequest
+# to keep Python module-load order valid (type aliases must precede use).
+HitlMode = Literal["disabled", "all_outbound"]
+
+# PR 7 — discriminator for which surface(s) routed an outbound message
+# into the HITL review queue. Surfaced on Message.review_trigger_source
+# (read-side responses) and on MessageReviewQueuedWebhookPayload.trigger_source
+# (webhook payload). Persisted in messages.review_trigger_source
+# (migration 061); RETAINED across approve/deny.
+ReviewQueueTriggerSource = Literal["mailbox_policy", "scanner", "both"]
+
+
+class ScannerPolicy(TypedDict, total=False):
+    language_mode: Literal["english_only", "allow_all_languages", "disabled"]
+    disabled_scanners: list[str]
+    disabled_proxy_criteria: list[str]
+    # PR 9 — per-type outbound PII send-safety tuning. Omitted keys use
+    # platform defaults; relaxed values are Pro+ gated by pii_advanced_controls.
+    outbound_pii_policy: OutboundPiiPolicy
+    # Approval workflow settings for outbound scanner-emitted review.
+    outbound_review_policy: OutboundReviewPolicy
+
+
+class CreateMailboxResponse(TypedDict):
+    id: str
+    name: str
+    address: str
+    # Migration 036 — new mailboxes default to 'blocklist'.
+    recipient_policy_mode: RecipientPolicyMode
+    # Migration 047 — inbound firewall mode; new mailboxes default to 'blocklist'.
+    sender_policy_mode: SenderPolicyMode
+    # PR 6 — per-mailbox HITL trigger; new mailboxes default to 'disabled'.
+    hitl_mode: HitlMode
+    # Migration 085 — thread-scoped reply bypass flag; new mailboxes default True.
+    allow_thread_replies: bool
+
+
+class Mailbox(TypedDict):
+    id: str
+    name: str
+    address: str
+    status: MailboxStatus
+    scanner_policy: ScannerPolicy | None
+    pii_mode: PiiMode
+    # Legacy attachment-access acceptance flag (migration 034). Retained for
+    # backward-compatible reads and audit history, but effective attachment
+    # exposure now comes from `attachment_exposure_mode` when set; otherwise
+    # the mailbox behaves as `metadata_only`.
+    attachment_access_enabled: bool
+    attachment_access_accepted_at: str | None
+    attachment_access_accepted_version: str | None
+    attachment_exposure_mode: AttachmentExposureMode
+    attachment_allowed_file_families: list[AttachmentAllowedFileFamily]
+    attachment_reauth_at: str | None
+    attachment_policy_version: str | None
+    image_raw_download_confirmed: bool
+    current_image_risk_version: str
+    attachment_image_access_accepted_at: str | None
+    attachment_image_access_accepted_version: str | None
+    # Always the current disclaimer version. Compare to accepted_version to
+    # detect when a "disclaimer updated" banner should render.
+    current_disclaimer_version: str
+    # True when the mailbox is on the legacy compat path
+    # (attachment_exposure_mode is null but attachment_access_enabled is true).
+    # Drives the dashboard re-acceptance banner; flips to false after the
+    # customer accepts an explicit mode. See
+    # docs/runbooks/legacy-attachment-access-migration.md.
+    legacy_wildcard_active: bool
+    # Migration 035 — default outbound sub-addressing rewrite mode.
+    default_subaddress_mode: SubaddressMode
+    # Migration 036 — recipient policy mode.
+    recipient_policy_mode: RecipientPolicyMode
+    # Migration 047 — inbound firewall mode (per-mailbox).
+    sender_policy_mode: SenderPolicyMode
+    # PR 6 — per-mailbox HITL trigger.
+    hitl_mode: HitlMode
+    # Migration 085 — thread-scoped reply bypass flag. Inert in blocklist mode;
+    # in allowlist mode permits a reply/follow-up to a visible inbound thread
+    # participant without a standing grant.
+    allow_thread_replies: bool
+    # PR 8.1 — per-detector redaction visibility. None = platform default
+    # (all 13 detectors redact with `<TYPE>` placeholder). Populated value
+    # is a partial map keyed by detector type; tier-gated Pro+ for any
+    # `redact: false` entry.
+    pii_redaction_config: PiiRedactionConfig | None
+    created_at: str
+
+
+class ListMailboxesResponse(TypedDict):
+    mailboxes: list[Mailbox]
+
+
+class UpdateMailboxResponse(TypedDict):
+    id: str
+    name: str
+    address: str
+    scanner_policy: ScannerPolicy | None
+    pii_mode: PiiMode
+    attachment_access_enabled: bool
+    attachment_access_accepted_at: str | None
+    attachment_access_accepted_version: str | None
+    attachment_exposure_mode: AttachmentExposureMode
+    attachment_allowed_file_families: list[AttachmentAllowedFileFamily]
+    attachment_reauth_at: str | None
+    attachment_policy_version: str | None
+    image_raw_download_confirmed: bool
+    current_image_risk_version: str
+    attachment_image_access_accepted_at: str | None
+    attachment_image_access_accepted_version: str | None
+    current_disclaimer_version: str
+    legacy_wildcard_active: bool
+    # Migration 035.
+    default_subaddress_mode: SubaddressMode
+    # Migration 036.
+    recipient_policy_mode: RecipientPolicyMode
+    # Migration 047.
+    sender_policy_mode: SenderPolicyMode
+    # PR 6 — per-mailbox HITL trigger.
+    hitl_mode: HitlMode
+    # Migration 085 — thread-scoped reply bypass flag.
+    allow_thread_replies: bool
+    # PR 8.1 — per-detector redaction visibility (None = platform default).
+    pii_redaction_config: PiiRedactionConfig | None
+
+
+# Mailbox attachment-access route request shapes.
+# Legacy `enable=False` remains the disable path. Legacy `enable=True` and
+# explicit `raw_download_selected_types` enablement/widening requires Pro+
+# entitlement plus a dashboard/session-cookie re-auth flow; Bearer-key SDK
+# callers can still disable, use safer modes, and perform same-or-narrower
+# raw-download writes.
+class AttachmentAccessLegacyRequest(TypedDict, total=False):
+    enable: bool
+    accept_disclaimer_version: str
+
+
+class AttachmentAccessPolicyRequest(TypedDict, total=False):
+    mode: AttachmentExposureMode
+    allowed_file_families: list[AttachmentAllowedFileFamilyRequest]
+    accept_disclaimer_version: str
+    accept_image_risk_version: str
+    reauth_token: str
+
+
+class AttachmentAccessResponse(TypedDict):
+    mailbox_id: str
+    mode: AttachmentExposureMode
+    allowed_file_families: list[AttachmentAllowedFileFamily]
+    accepted_at: str | None
+    accepted_version: str | None
+    attachment_access_enabled: bool
+    attachment_access_accepted_at: str | None
+    attachment_access_accepted_version: str | None
+    image_raw_download_confirmed: bool
+    current_image_risk_version: str
+    attachment_image_access_accepted_at: str | None
+    attachment_image_access_accepted_version: str | None
+    current_disclaimer_version: str
+    # Mirrors Mailbox.legacy_wildcard_active; flips to false after a
+    # successful explicit-shape write.
+    legacy_wildcard_active: bool
+
+
+# Migration 036 — allowlist entries.
+class _AllowlistEntryRequired(TypedDict):
+    email: str
+    mailbox_id: str
+    created_at: str
+    added_by_actor_type: str | None
+    added_by_actor_id: str | None
+
+
+class AllowlistEntry(_AllowlistEntryRequired, _HasPatternType):
+    """Allowlist entry. `pattern_type` present on 0.5.0+ server responses."""
+
+
+class ListAllowlistResponse(TypedDict):
+    allowlist: list[AllowlistEntry]
+    next_cursor: str | None
+
+
+class _AddAllowlistResponseRequired(TypedDict):
+    email: str
+    mailbox_id: str
+    created_at: str | None
+    already_existed: bool
+    added_by_actor_type: str | None
+    added_by_actor_id: str | None
+
+
+class AddAllowlistResponse(_AddAllowlistResponseRequired, _HasPatternType):
+    """Response of POST /v1/mailboxes/:id/allowlist."""
+
+
+class _BulkAllowlistAddedRequired(TypedDict):
+    email: str
+    created_at: str
+
+
+class _BulkAllowlistAdded(_BulkAllowlistAddedRequired, _HasPatternType):
+    """Bulk-added row — `pattern_type` present on 0.5.0+ servers."""
+
+
+class _BulkAllowlistInvalid(TypedDict):
+    email: str
+    reason: str
+
+
+class _BulkAllowlistCounts(TypedDict):
+    added: int
+    already_existed: int
+    invalid: int
+    total: int
+
+
+class BulkAddAllowlistResponse(TypedDict):
+    added: list[_BulkAllowlistAdded]
+    already_existed: list[str]
+    invalid: list[_BulkAllowlistInvalid]
+    counts: _BulkAllowlistCounts
+
+
+class DeleteAllowlistResponse(TypedDict, total=False):
+    status: str
+    email: str
+    mailbox_id: str
+    created_at: str
+    # Sprint 039 — `email` or `@domain.com`. Optional for older servers.
+    pattern_type: RecipientPatternType
+
+
+# === Messages ===
+
+class HoldContext(TypedDict):
+    """inline-scan-verdict-on-send §2b — policy/HITL hold channel.
+
+    Present (non-null) only when applyHitlPolicy changed the scanner's
+    decision so delivery `status` diverges from `scan.verdict`; when present,
+    `summary_reasons` carries >=1 customer-safe line.
+    """
+    trigger_source: Literal["mailbox_policy", "scanner", "both"]
+    summary_reasons: list[str]
+
+
+class SendMessageResponse(TypedDict):
+    message_id: str
+    status: Literal["sent", "quarantined", "blocked", "pending_review"]
+    warning: str | None
+    # Customer-facing scanner verdict; null when no scan results.
+    scan: NotRequired["ScanSummary | None"]
+    # Policy/HITL hold reason; null when scan explains the hold or status='sent'.
+    hold_context: NotRequired["HoldContext | None"]
+    daily_limit: int
+    sends_remaining: int
+
+
+class MessageSummary(TypedDict, total=False):
+    """List-response item shape.
+
+    PR 7 marked the type total=False so the additive review_trigger_source
+    + body_preview fields can be modeled as optional without breaking
+    existing total=True consumers. The four core required fields below
+    are still emitted by the server on every response.
+    """
+    id: Required[str]
+    direction: Required[MessageDirection]
+    state: Required[MessageState]
+    sender: Required[str]
+    recipient: Required[str]
+    subject: Required[str]
+    # Owning mailbox name (mailboxes.name), resolved so agents don't see a
+    # bare mailbox UUID.
+    mailbox_name: NotRequired[str | None]
+    # Customer-facing scan summary; null when scan_result_json was null at-rest.
+    # Replaces the legacy per-row scan_results array.
+    scan: NotRequired["ScanSummary | None"]
+    # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
+    subaddress_instance_id: Required[str | None]
+    # Migration 047 — present (non-null) only on state='firewall_blocked'.
+    firewall_block: Required[FirewallBlock | None]
+    # S7a — thread key. Stripped Message-Id for threaded mail; null for
+    # standalone rows where messages.thread_id IS NULL. Surfaced so search-
+    # result navigation can route inbound results to the correct thread
+    # without a follow-up GET.
+    thread_id: Required[str | None]
+    created_at: Required[str]
+    read_at: Required[str | None]
+    # PR 7 (migration 061) — discriminator for which surface routed this
+    # row into pending_review. None for any row that never went through
+    # pending_review, AND for legacy pre-PR-7.1 pending_review rows
+    # (those came from PR 6 mailbox-policy promotion only — dashboards
+    # render None → "Policy" by inference). RETAINED across approve/deny.
+    review_trigger_source: NotRequired[ReviewQueueTriggerSource | None]
+    # Plaintext, whitespace-normalized, 200-character list excerpt.
+    body_preview: NotRequired[str | None]
+    # S7 NTH-003 — server-computed deep link into the web inbox shell, or None
+    # when PUBLIC_LINK_BASE_URL is unset on the server (fail-closed).
+    dashboard_url: NotRequired[str | None]
+
+
+class MarkMessageReadResponse(TypedDict):
+    """S7a — POST /v1/messages/:id/read response."""
+    message_id: str
+    # The row's read_at after the call. For ineligible rows (outbound,
+    # deleted, firewall_blocked) this is the existing value (possibly null).
+    read_at: str | None
+
+
+class MarkThreadReadResponse(TypedDict):
+    """S7a — POST /v1/mailboxes/:id/threads/:thread_id/read response."""
+    thread_id: str
+    # Number of rows newly stamped this call (excludes already-read).
+    marked_count: int
+
+
+class AttachmentMeta(TypedDict, total=False):
+    filename: str
+    content_type: str
+    size: int
+    hash: str
+    policy_action: AttachmentPolicyAction
+    sniffed_mime_type: str
+    declared_mime_type: str
+    mime_mismatch: bool
+    av_verdict: AvVerdict
+    av_signature: str
+    av_scanned_at: str
+    stored: bool
+    content_id: str
+    content_disposition: str
+    inline: bool
+    raw_retention: AttachmentRawRetentionStatus
+    raw_deleted_at: str
+    raw_retention_reason: str
+
+
+class AttachmentPreviewSummary(TypedDict):
+    preview_status: AttachmentDerivativeStatus | None
+    preview_kind: AttachmentPreviewKind | None
+    preview_reason_code: str | None
+    preview_char_count: int | None
+    preview_page_count: int | None
+    preview_truncated: bool | None
+    preview_generated_at: str | None
+
+
+class MessageAttachment(AttachmentMeta, total=False):
+    preview_status: AttachmentDerivativeStatus | None
+    preview_kind: AttachmentPreviewKind | None
+    preview_reason_code: str | None
+    preview_char_count: int | None
+    preview_page_count: int | None
+    preview_truncated: bool | None
+    preview_generated_at: str | None
+
+
+# === URL reputation (Google Web Risk) — additive ScanResult fields ===
+#
+# Mirror of packages/sdk/src/types.ts WebRiskLearnMore + WebRiskWarning +
+# the additive ScanResult.expires_at / ScanResult.warning fields.
+# Populated only on unexpired url-reputation malicious verdicts; absent
+# everywhere else (the server-side sanitizer scrubs these fields on
+# expiry, so consumers don't need to implement client-side expiry logic).
+
+# Optional documentation literal — `WebRiskLearnMore.threat_type` keeps
+# the wider `str` type (matches the TS SDK and is forward-compatible
+# with future Web Risk threat types). Use this Literal in code that
+# wants exhaustive checking of the four currently-defined threat types.
+WebRiskThreatType = Literal[
+    "MALWARE",
+    "SOCIAL_ENGINEERING",
+    "UNWANTED_SOFTWARE",
+    "SOCIAL_ENGINEERING_EXTENDED_COVERAGE",
+]
+
+
+class WebRiskLearnMore(TypedDict):
+    """Per-threat-type learn-more link inside `WebRiskWarning.learn_more`.
+
+    `threat_type` is `str` (not the `WebRiskThreatType` literal) to match
+    the TS SDK contract and stay forward-compatible with new threat
+    classes Google may add. Render the URL as an explicit `<a>` element
+    when surfacing the warning to end users.
+    """
+
+    threat_type: str
+    url: str
+
+
+class WebRiskWarning(TypedDict):
+    """Structured Google Web Risk warning payload.
+
+    Present on `ScanResult.warning` only for unexpired url-reputation
+    malicious verdicts. The server-side sanitizer clears this field
+    once `expires_at` passes, so any warning reaching the SDK is safe
+    to render without a client-side expiry re-check.
+
+    Render `attribution_url` and each `learn_more[].url` as explicit
+    `<a>` elements. Never auto-linkify the parent `ScanResult.reason`
+    string — it's the plain-text fallback for surfaces that can't
+    render structured links (admin CLI, plain-text logs).
+    """
+
+    qualified_wording: str
+    attribution_text: str
+    attribution_url: str
+    learn_more: list[WebRiskLearnMore]
+    affected_urls: list[str]
+
+
+class _ScanResultRequired(TypedDict):
+    scanner: str
+    decision: PolicyDecision
+    confidence: float
+    reason: str
+
+
+class ScanResult(_ScanResultRequired, total=False):
+    """Per-scanner verdict on a message.
+
+    The four required fields (scanner, decision, confidence, reason)
+    are emitted by every scanner. `expires_at` and `warning` are
+    additive and only appear on url-reputation results — see
+    `WebRiskWarning` for the contract. `pii_type` (PR 9) is present only
+    on local outbound `scanner="pii"` results and identifies the stable
+    local category (`ssn`, `credit_card`, or `phone_number`).
+    """
+
+    # Vendor-mandated lifetime (currently only url-reputation carries
+    # this via Google Web Risk `expireTime`). The server-side sanitizer
+    # clears it alongside `warning` + rewrites `reason` to a neutral
+    # placeholder once the timestamp passes. Absence means either the
+    # entry is unexpiring (non-url-reputation) or it was already
+    # scrubbed by the sanitizer.
+    expires_at: str
+    pii_type: OutboundPiiType
+    # Structured Web Risk warning. Populated only on unexpired
+    # url-reputation malicious verdicts. See `WebRiskWarning`.
+    warning: WebRiskWarning
+    # Structural pointer into attachments[] for per-attachment findings (e.g.
+    # the attachment-type-mismatch scanner). Surfaced as
+    # ScanFinding.attachment_index; never parsed from reason.
+    attachment_index: int
+
+
+# === Customer-facing scan summary (renderScanSummary output) ===
+#
+# Mirror of packages/shared/src/scan-summary.ts. Replaces the legacy
+# `scan_results: list[ScanResult]` shape on every read endpoint. Default
+# view returns non-allow findings inline with typed subfields; `view='verbose'`
+# adds clean-allow findings for the full audit trail. Vendor names never
+# appear in any field; Web Risk attribution survives inside findings[i].warning.
+ScanVerdict = Literal["clean", "warning", "review_required", "blocked", "quarantined"]
+
+ScanCategory = Literal[
+    "prompt_injection",
+    "function_call_risk",
+    "harmful_content",
+    "liability_risk",
+    "pii",
+    "phishing_url",
+    "image_exfil",
+    "malware",
+    "attachment_policy",
+    "mime_mismatch",
+    "attachment_type_mismatch",
+    "spam",
+    "language_policy",
+    "recipient_policy",
+    "secret_detected",
+    "content_similarity",
+    "scan_incomplete",
+]
+
+ScanSubtype = Literal[
+    # prompt_injection
+    "jailbreak",
+    "instruction_injection",
+    # harmful_content
+    "toxicity",
+    "violence",
+    "sexual_content",
+    "hate_speech",
+    "harassment",
+    "self_harm",
+    "profanity",
+    # secret_detected
+    "secret_value",
+    "outbound_confidentiality_leak",
+]
+
+ScanAttachmentPolicyAction = Literal[
+    "quarantine_message",
+    "metadata_only_after_rewrite",
+    "derived_text_finding",
+]
+
+
+class ScanCategorySummary(TypedDict):
+    category: ScanCategory
+    decision: PolicyDecision
+
+
+class ScanFinding(TypedDict, total=False):
+    category: Required[ScanCategory]
+    decision: Required[PolicyDecision]
+    reason: Required[str | None]
+    warning: WebRiskWarning
+    expires_at: str
+    pii_type: OutboundPiiType
+    subtype: ScanSubtype
+    attachment_index: int
+    # Filename of the attachment this finding refers to
+    # (attachments[attachment_index].filename). Stamped at scan time so it
+    # reaches list/wait/send/draft surfaces that carry no attachments[] array.
+    attachment_filename: str
+    attachment_policy_action: ScanAttachmentPolicyAction
+    # Inference-failure-transparency plan §5.5 — discriminates infrastructure
+    # failures from model judgments. Present only on non-allow findings backed
+    # by external inference.
+    failure_class: Literal["inference_error", "model_judgment"]
+    # RL-UAT-012/013 — structural handling guidance for the agent.
+    agent_instructions: list[str]
+
+
+class ScanSummary(TypedDict):
+    verdict: ScanVerdict
+    categories: list[ScanCategorySummary]
+    findings: list[ScanFinding]
+
+
+ScanView = Literal["summary", "verbose"]
+
+
+class MessageBody(TypedDict):
+    format: Literal["text", "html"]
+    content: str | None
+    char_count: int
+    returned_char_count: int
+    truncated: bool
+
+
+class GetMessageResponse(TypedDict, total=False):
+    """GET /v1/messages/:id detail response.
+
+    total=False so PR 6 review-resolution metadata + PR 7 review trigger
+    source can be modeled as optional fields. The required-keys subset
+    (everything except review_outcome / reviewed_* / review_reason /
+    review_trigger_source) is enforced by the server.
+    """
+    id: Required[str]
+    # Owning mailbox UUID (lets clients derive the mailbox, e.g. reply attachments).
+    mailbox_id: Required[str]
+    # Owning mailbox name (mailboxes.name), resolved so agents don't see a
+    # bare mailbox UUID.
+    mailbox_name: NotRequired[str | None]
+    direction: Required[MessageDirection]
+    state: Required[MessageState]
+    sender: Required[str]
+    recipient: Required[str]
+    subject: Required[str]
+    body: Required[MessageBody]
+    attachments: Required[list[MessageAttachment]]
+    scan: Required[ScanSummary | None]
+    thread_id: Required[str | None]
+    in_reply_to: Required[str | None]
+    # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
+    subaddress_instance_id: Required[str | None]
+    # Migration 047 — present (non-null) only on state='firewall_blocked'.
+    firewall_block: Required[FirewallBlock | None]
+    read_at: Required[str | None]
+    created_at: Required[str]
+    # S7 NTH-003 — server-computed deep link into the web inbox shell, or None
+    # when PUBLIC_LINK_BASE_URL is unset on the server (fail-closed).
+    dashboard_url: NotRequired[str | None]
+    # PR 6 — review-resolution metadata. Populated only after a row passes
+    # through approve/deny; None on pending_review and pre-PR-6 rows.
+    review_outcome: NotRequired[Literal["approved", "denied"] | None]
+    reviewed_at: NotRequired[str | None]
+    reviewed_by_type: NotRequired[str | None]
+    reviewed_by_id: NotRequired[str | None]
+    review_reason: NotRequired[str | None]
+    # PR 7 (migration 061) — discriminator for which surface routed this
+    # row into pending_review. See MessageSummary above for the None-fallback
+    # semantics (legacy → "Policy" by inference). RETAINED across approve/deny.
+    review_trigger_source: NotRequired[ReviewQueueTriggerSource | None]
+
+
+# === message.received webhook payload (with optional URL-reputation safety) ===
+#
+# Mirror of packages/sdk/src/types.ts MessageReceivedSafetySignal +
+# MessageReceivedWebhookPayload. The `safety` field is additive — it
+# appears only when the url-reputation scanner returned
+# `allow_with_warning` (typically because Web Risk's lists were stale,
+# the confirm API timed out, or the kill switch was on). It is NOT
+# populated from worstDecision across all scanners — other warning
+# scanners' reasons embed customer content that's kept off the
+# message.received wire. `reason` is a ReplyLayer-authored count-only
+# string ("Could not verify reputation for N URL(s) — treat with
+# caution"); it never contains customer URLs.
+
+class MessageReceivedSafetySignal(TypedDict):
+    """Optional `data.safety` block on `message.received` webhook events."""
+
+    decision: Literal["allow_with_warning"]
+    reason: str
+
+
+class _MessageReceivedWebhookPayloadRequired(TypedDict):
+    message_id: str
+    mailbox_id: str
+    sender: str
+    recipient: str
+    subject: str
+    received_at: str
+    # Migration 035 — `<REDACTED>` under mailbox pii_mode=redacted.
+    subaddress_instance_id: str | None
+
+
+class MessageReceivedWebhookPayload(
+    _MessageReceivedWebhookPayloadRequired, total=False,
+):
+    """Body of a `message.received` webhook event.
+
+    `safety` appears only when a url-reputation `allow_with_warning`
+    ScanResult was present on the message. Absent for "all clean" or
+    when only non-url-reputation scanners returned warnings.
+    """
+
+    safety: MessageReceivedSafetySignal
+
+
+class AttachmentPreviewWebhookPayloadBase(TypedDict):
+    message_id: str
+    mailbox_id: str
+    attachment_index: int
+    variant: AttachmentDerivativeVariant
+
+
+class AttachmentPreviewQueuedWebhookPayload(AttachmentPreviewWebhookPayloadBase):
+    queued_at: str
+
+
+class AttachmentPreviewReadyWebhookPayload(AttachmentPreviewWebhookPayloadBase):
+    ready_at: str
+    kind: AttachmentPreviewKind
+    char_count: int | None
+    page_count: int | None
+    truncated: bool
+
+
+class AttachmentPreviewBlockedWebhookPayload(AttachmentPreviewWebhookPayloadBase):
+    blocked_at: str
+    reason_code: str | None
+
+
+class AttachmentPreviewFailedWebhookPayload(AttachmentPreviewWebhookPayloadBase):
+    failed_at: str
+    reason_code: str | None
+
+
+# PR 6 — HITL review queue webhook payloads. Source-of-truth contract:
+# docs/webhooks.md (PR 6 rows) + plans/tier-feature-gating-pr6-hitl-review-queue.md §9.
+#
+# `message.review.queued` carries subject + recipient (subject to PII
+# redaction when the source mailbox's pii_mode is 'redacted'); `summary_reasons`
+# is always non-empty (the helper synthesizes a policy reason when the trigger
+# is mailbox-policy and there are no scanner findings). Raw `scan_results`
+# is intentionally NOT included.
+MessageReviewOrigin = Literal["fresh_send", "reply", "draft"]
+
+
+class _MessageReviewQueuedWebhookPayloadRequired(TypedDict):
+    """Required keys for the queued review webhook payload.
+
+    Round-2 audit P3 fix — TS SDK and the runtime contract require all
+    these fields on every emit; only `trigger_source` is optional for
+    wire-additive compatibility with pre-PR-7 emit sites. Mirrors the
+    `MessageReceivedWebhookPayload` required-base pattern.
+    """
+    message_id: str
+    mailbox_id: str
+    direction: Literal["outbound"]
+    subject: str
+    recipient: str
+    summary_reasons: list[str]
+    origin: MessageReviewOrigin
+
+
+class MessageReviewQueuedWebhookPayload(
+    _MessageReviewQueuedWebhookPayloadRequired, total=False,
+):
+    """v1 outbound-only HITL review queue webhook payload.
+
+    PR 7 added the optional `trigger_source` discriminator (which
+    surface(s) routed the message into pending_review). Distinct from
+    `origin` (call-site valued); they are independent dimensions.
+    PR 7.1 + PR 7.3 always populate `trigger_source` server-side, but
+    the type stays NotRequired for wire-additive compatibility with
+    pre-PR-7 emit sites a customer may still receive during a deploy
+    rollout window.
+    """
+    trigger_source: ReviewQueueTriggerSource
+
+
+# `.approved` and `.denied` carry no PII fields — only operator-context.
+# Both fire regardless of dispatch outcome (action is the signal; Mailgun
+# result is captured by message.delivered / .bounced / .dispatch_failed).
+class MessageReviewApprovedWebhookPayload(TypedDict):
+    message_id: str
+    mailbox_id: str
+    reviewed_by_type: Literal["admin", "user"]
+    reviewed_at: str                          # ISO-8601
+    reason: str | None
+    prior_state: Literal["pending_review"]
+
+
+class MessageReviewDeniedWebhookPayload(TypedDict):
+    message_id: str
+    mailbox_id: str
+    reviewed_by_type: Literal["admin", "user"]
+    reviewed_at: str
+    reason: str | None
+    prior_state: Literal["pending_review"]
+
+
+class WaitResponse(TypedDict):
+    message: MessageSummary | None
+
+
+class ReleaseResponse(TypedDict):
+    status: Literal["released", "sent", "blocked"]
+    message_id: str
+
+
+class BlockResponse(TypedDict):
+    status: Literal["blocked"]
+    message_id: str
+
+
+# === Drafts ===
+#
+# A draft is a message in state='draft'. Scanner runs at create + update and
+# authoritatively re-runs on send. See SyncDrafts / AsyncDrafts in
+# resources/drafts.py.
+
+class CreateDraftRequest(TypedDict, total=False):
+    # Fresh mode requires mailbox_id/to/subject/body; thread mode (thread_id
+    # present, migration 085) derives mailbox_id/subject and makes `to` an
+    # optional participant selector. TypedDict total=False marks everything
+    # optional for IDE ergonomics — the server enforces the mode rules.
+    mailbox_id: str
+    to: str
+    subject: str
+    body: str
+    html: str
+    in_reply_to_message_id: str
+    # Migration 085 — continue an existing thread; mutually exclusive with
+    # in_reply_to_message_id.
+    thread_id: str
+    # Migration 035 — sub-addressing routing hint, persisted on the draft.
+    subaddress_instance_id: str
+    subaddress_mode: SubaddressMode
+    # Outbound attachment handles (plans/outbound-attachment-ux.md) — held on
+    # the draft and consumed once at dispatch. Requires the mailbox to have
+    # outbound attachments enabled (Pro+).
+    attachment_ids: list[str]
+
+
+class UpdateDraftRequest(TypedDict, total=False):
+    # All optional — server rejects an empty body with 400.
+    to: str
+    subject: str
+    body: str
+    html: str
+    # Migration 035 — 3-way PATCH sigil: str sets/updates, None clears
+    # (auto-clears subaddress_mode when instance is cleared), omitted is
+    # no-change. Type parity with TS SDK UpdateDraftRequest.
+    subaddress_instance_id: str | None
+    subaddress_mode: SubaddressMode | None
+    # Outbound attachment handles: list replaces the set, None clears all,
+    # omitted is no-change (mirror of the JSON-schema ['array','null']).
+    attachment_ids: list[str] | None
+
+
+class ListDraftsParams(TypedDict, total=False):
+    limit: int
+    before: str
+    auto_paginate: bool
+
+
+class DraftResponse(TypedDict):
+    id: str
+    mailbox_id: str
+    # Owning mailbox name (mailboxes.name). Additive/optional.
+    mailbox_name: NotRequired[str | None]
+    state: Literal["draft", "available", "deleted"]
+    sender: str
+    recipient: str
+    subject: str
+    body: MessageBody
+    scan: ScanSummary
+    worst_decision: PolicyDecision
+    thread_id: str | None
+    in_reply_to: str | None
+    # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
+    subaddress_instance_id: str | None
+    subaddress_mode: SubaddressMode | None
+    created_at: str
+    updated_at: str
+
+
+class DraftSummary(TypedDict):
+    id: str
+    mailbox_id: str
+    # Owning mailbox name (mailboxes.name). Additive/optional.
+    mailbox_name: NotRequired[str | None]
+    state: Literal["draft"]
+    sender: str
+    recipient: str
+    subject: str
+    worst_decision: PolicyDecision
+    # Migration 035 — may be `<REDACTED>` under mailbox pii_mode=redacted.
+    subaddress_instance_id: str | None
+    created_at: str
+    updated_at: str
+
+
+class ListDraftsResponse(TypedDict):
+    drafts: list[DraftSummary]
+
+
+# === Threads ===
+
+class ThreadSummary(TypedDict):
+    id: str
+    subject: str
+    first_message_at: str
+    last_message_at: str
+    message_count: int
+    unread_count: int
+    participants: list[str]
+
+
+class GetThreadResponse(TypedDict):
+    id: str
+    mailbox_id: str
+    # Owning mailbox name (mailboxes.name). Additive/optional.
+    mailbox_name: NotRequired[str | None]
+    subject: str
+    message_count: int
+    messages: list[GetMessageResponse]
+
+
+# === Attachments ===
+
+class AttachmentDownloadResponse(TypedDict):
+    url: str
+    expires_at: str
+    content_type: str
+    filename: str
+    size: int
+    av_verdict: str | None
+
+
+class AttachmentPreviewMetadata(TypedDict):
+    filename: str
+    content_type: str
+    size: int
+    hash: str
+
+
+class AttachmentPreviewBody(TypedDict):
+    kind: AttachmentPreviewKind
+    content: str
+    truncated: bool
+    char_count: int | None
+    page_count: int | None
+    extractor: str
+    generated_at: str
+
+
+class AttachmentPreviewResponse(TypedDict):
+    attachment: AttachmentPreviewMetadata
+    preview: AttachmentPreviewBody
+
+
+# Outbound-attachment content-scan lifecycle (POST /v1/attachments):
+#   pending → async text content-scan not yet run; referencing on a send → 409
+#   clean   → no findings; sendable
+#   flagged → secret/PII finding(s); still sendable, findings flow to the
+#             message verdict (block/quarantine by severity, like a body finding)
+#   error   → scan failed; fail-closed (cannot be sent)
+OutboundAttachmentScanStatus = Literal["pending", "clean", "flagged", "error"]
+
+
+class UploadAttachmentResponse(TypedDict):
+    """201 body of POST /v1/attachments. ``id`` is the opaque handle to put in a
+    send/reply/draft ``attachment_ids`` list. ``scan`` is present only when the
+    synchronous filename scan produced findings. ``content_scan_status`` is
+    always ``"pending"`` at upload time — poll ``get_upload(id)`` until terminal
+    before referencing the handle."""
+    id: str
+    filename: str
+    content_type: str
+    size: int
+    hash: str
+    scan: NotRequired[ScanSummary]
+    content_scan_status: OutboundAttachmentScanStatus
+
+
+class ConsumedAttachmentResponse(TypedDict):
+    """GET /v1/attachments/:id once the handle has been consumed by a send."""
+    id: str
+    status: Literal["consumed"]
+    consumed_at: str
+    consumed_message_id: str | None
+
+
+# GET /v1/attachments/:id returns the active-handle shape (UploadAttachmentResponse)
+# or, once consumed, ConsumedAttachmentResponse — discriminate on the `status` key.
+GetUploadAttachmentResponse = Union[UploadAttachmentResponse, ConsumedAttachmentResponse]
+
+
+# === Webhooks ===
+
+class CreateWebhookResponse(TypedDict):
+    id: str
+    url: str
+    description: str | None
+    enabled: bool
+    enabled_events: list[WebhookEventType]
+    signing_secret: str
+    created_at: str
+
+
+class WebhookSummary(TypedDict):
+    id: str
+    url: str
+    description: str | None
+    enabled: bool
+    enabled_events: list[WebhookEventType]
+    created_at: str
+    updated_at: str
+    # D6: health fields surfaced by the delivery worker
+    consecutive_failures: int
+    last_success_at: str | None
+    last_failure_at: str | None
+    last_error: str | None
+    disabled_at: str | None
+    disabled_reason: str | None
+
+
+class ListWebhooksResponse(TypedDict):
+    webhooks: list[WebhookSummary]
+
+
+class RotateWebhookSecretResponse(TypedDict):
+    signing_secret: str
+
+
+class TestWebhookResponse(TypedDict):
+    delivery_id: str
+
+
+WebhookDeliveryStatus = Literal["pending", "delivering", "delivered", "failed"]
+
+
+class WebhookDeliverySummary(TypedDict):
+    id: str
+    event_type: str
+    status: WebhookDeliveryStatus
+    http_status: int | None
+    attempt_count: int
+    created_at: str
+    delivered_at: str | None
+    failed_at: str | None
+    next_retry_at: str | None
+    response_preview: str | None
+
+
+# deliveries + has_more are always present; cursor fields appear only
+# when has_more is True. Split into a required base + total=False extension
+# so consumers don't need `if 'deliveries' in resp` defensive checks.
+class _ListDeliveriesRequired(TypedDict):
+    deliveries: list[WebhookDeliverySummary]
+    has_more: bool
+
+
+class ListDeliveriesResponse(_ListDeliveriesRequired, total=False):
+    next_before_at: str
+    next_before_id: str
+
+
+class RetryDeliveryResponse(TypedDict):
+    delivery_id: str
+    status: Literal["pending"]
+
+
+# === Recipients ===
+
+class AddRecipientResponse(TypedDict):
+    id: str
+    email: str
+    status: RecipientStatus
+    created_at: str
+
+
+class Recipient(TypedDict):
+    id: str
+    email: str
+    status: RecipientStatus
+    created_at: str
+    confirmed_at: str | None
+
+
+class ListRecipientsResponse(TypedDict):
+    recipients: list[Recipient]
+
+
+# === Suppressions ===
+
+class _SuppressionRequired(TypedDict):
+    email: str
+    reason: SuppressionReason
+    source: str
+    created_at: str
+    added_by_actor_type: str | None
+    added_by_actor_id: str | None
+
+
+class _SuppressionOptional(TypedDict, total=False):
+    # Migration 051 — complaint history columns.
+    #
+    # `latest_complaint_at` is the LOCK SIGNAL: the most recent moment a
+    # complaint signal was recorded (worker-received provider event OR
+    # Mailgun-sync observation). Customer DELETE on rows with non-null
+    # latest_complaint_at is rejected with 409
+    # RECIPIENT_BLOCKLIST_COMPLAINT_LOCKED. complaint_count does NOT
+    # affect lock behavior.
+    #
+    # `complaint_count` is the count of distinct provider complaint
+    # events received by the worker. Mailgun-sync observations do NOT
+    # increment it — a row locked by sync alone may show
+    # complaint_count=0 while latest_complaint_at is set.
+    latest_complaint_at: str | None
+    complaint_count: int
+
+
+class Suppression(_SuppressionRequired, _HasPatternType, _SuppressionOptional):
+    """Suppression entry. `pattern_type` present on 0.5.0+ server responses;
+    `latest_complaint_at` and `complaint_count` present on migration-051+ servers."""
+
+
+class ListSuppressionsResponse(TypedDict):
+    suppressions: list[Suppression]
+    next_cursor: str | None
+
+
+class AddSuppressionRequest(TypedDict):
+    email: str
+
+
+class _AddSuppressionResponseRequired(TypedDict):
+    email: str
+    reason: Literal["manual"]
+    source: Literal["customer"]
+    created_at: str | None
+    already_existed: bool
+    added_by_actor_type: str | None
+    added_by_actor_id: str | None
+
+
+class AddSuppressionResponse(_AddSuppressionResponseRequired, _HasPatternType):
+    """Response of POST /v1/suppressions."""
+
+
+class BulkAddSuppressionsRequest(TypedDict):
+    emails: list[str]
+
+
+class _BulkAddedRowRequired(TypedDict):
+    email: str
+    created_at: str
+
+
+class BulkAddedRow(_BulkAddedRowRequired, _HasPatternType):
+    """Bulk-added row. `pattern_type` present on 0.5.0+ server responses."""
+
+
+class BulkAddInvalidEntry(TypedDict):
+    email: str
+    reason: str
+
+
+class BulkAddCounts(TypedDict):
+    added: int
+    already_existed: int
+    invalid: int
+    total: int
+
+
+class BulkAddSuppressionsResponse(TypedDict):
+    added: list[BulkAddedRow]
+    already_existed: list[str]
+    invalid: list[BulkAddInvalidEntry]
+    counts: BulkAddCounts
+
+
+class _DeleteSuppressionResponseRequired(TypedDict):
+    status: str
+    email: str
+    reason: str
+    source: str
+    created_at: str
+
+
+class DeleteSuppressionResponse(_DeleteSuppressionResponseRequired, _HasPatternType):
+    """Response of DELETE /v1/suppressions/:email."""
+
+
+# === API Keys ===
+
+class CreateApiKeyResponse(TypedDict):
+    id: str
+    api_key: str
+    role: ApiKeyRole
+    label: str | None
+    mailbox_ids: list[str]
+
+
+class ApiKeySummary(TypedDict):
+    id: str
+    prefix: str
+    status: str
+    role: str | None
+    label: str | None
+    mailbox_ids: list[str]
+    created_at: str
+    last_used_at: str | None
+
+
+class ListApiKeysResponse(TypedDict):
+    keys: list[ApiKeySummary]
+
+
+class RotateKeyResponse(TypedDict):
+    api_key: str
+
+
+# === Account ===
+
+StorageUsageState = Literal["normal", "warning", "near_full", "over_limit"]
+
+
+class UsageToday(TypedDict):
+    count: int
+    limit: int
+    day: str
+
+
+class StorageUsageBreakdown(TypedDict):
+    raw_mime_bytes: int
+    derivative_bytes: int
+
+
+class StorageUsage(TypedDict):
+    used_bytes: int
+    limit_bytes: int | None
+    percent_used: float | None
+    state: StorageUsageState
+    breakdown: StorageUsageBreakdown
+
+
+class UsageResponse(TypedDict, total=False):
+    today: UsageToday
+    history: list[dict[str, Any]]
+    mailbox_count: int
+    mailbox_limit: int
+    storage: Required[StorageUsage]
+    # PR 6 — REQUIRED. Mirrors the TS SDK + API schema: a missing field
+    # surfaces as schema validation failure (500) on the server, never
+    # silent zero. Other fields stay total=False (optional) for backwards
+    # compat with consumers that relied on partial-dict semantics.
+    pending_review_count: Required[int]
+    rates: dict[str, float]
+    health: dict[str, Any]
+    trust: dict[str, Any]
+
+
+# Agent-accessible send-budget preflight (GET /v1/accounts/quota, RL-UAT-015/D6).
+# `today.limit` is the EFFECTIVE (trust-derived) daily cap, not the raw tier cap.
+# The `scope` discriminator disambiguates the two []-mailbox cases: "admin" with
+# [] => ALL mailboxes; "agent" with [] => a zero-bound agent key with NO send
+# capability.
+class QuotaToday(TypedDict):
+    count: int
+    limit: int
+    day: str
+
+
+class QuotaResponse(TypedDict):
+    today: QuotaToday
+    sends_remaining: int
+    reset_at: str
+    scope: Literal["admin", "agent"]
+    bound_mailbox_ids: list[str]
+
+
+# === Health ===
+
+class ProviderHealth(TypedDict, total=False):
+    healthy: bool
+    configured: bool
+    events_configured: bool
+
+
+class HealthResponse(TypedDict, total=False):
+    status: Literal["ok", "degraded", "down"]
+    database: bool
+    providers: dict[str, ProviderHealth]
+    kms: bool
+    scanner: bool
+    spam_filter: bool
+    queue_depth: int
+    timestamp: str
+    # Additive capability tokens advertised by the server (e.g.
+    # "messages.has_attachment_filter"). Absent on older servers — treat a
+    # missing token as "feature unsupported".
+    capabilities: list[str]