e2a 2.2.0__tar.gz → 2.3.0__tar.gz

e2a-2.3.0/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## 2.3.0
+
+### Added
+- `idempotency_key` parameter on `E2AClient.send()` / `.reply()` and their async
+  counterparts (and on the lower-level `E2AApi.send_email()` /
+  `reply_to_message()`). When supplied, it is sent as the `Idempotency-Key`
+  header so the server can deduplicate retries of the same send/reply. When
+  omitted, the SDK generates a fresh UUIDv4 per call — that gives
+  network-layer retry safety only; supply a stable key derived from the
+  triggering event (e.g. the inbound message id or a job id) to deduplicate
+  across an explicit retry loop.
+- `InboundEmail.reply_to` and `AsyncInboundEmail.reply_to` (`list[str]`) — the
+  parsed `Reply-To:` header from the inbound message, surfaced as a first-class
+  field so consumers no longer need to re-parse `raw_message` with stdlib
+  `email.message_from_bytes()`. Empty list when the header is absent; the SDK
+  never silently falls back to `sender`. Use this when the sender is a no-reply
+  notifications mailbox (Granola, GitHub, CI bots) and you need the actual
+  correspondent.
+- `MessageSummary.reply_to` (`list[str]`) on the REST polling path — the list
+  endpoint now mirrors the same field.
+- `reply_to` added to `unverified_payload` for forensic inspection without
+  unlocking gated access.
+
+### Reply-To trust path (decision)
+`reply_to` is trusted on the same terms as `to`, `cc`, `recipient`,
+`subject`, and the body fields: the e2a server parses it from
+`raw_message`, places it in the JSON envelope, and TLS protects the wire
+to your webhook URL. Treat the field as trustworthy once
+`verify_signature()` succeeds **and** you're confident in your
+relay-to-webhook connection (or via `client.get_message(...)`, which uses
+the authenticated REST channel).
+
+**What `verify_signature()` does not prove:** the HMAC binds a fixed set
+of auth headers and `body_hash = SHA-256(raw_message)`. It does not sign
+the JSON envelope itself, and the SDK reads `reply_to`, `to`, `cc`, etc.
+from that envelope rather than re-parsing `raw_message`. So an attacker
+who can modify the JSON wrapping after signing — but cannot modify
+`raw_message` or the signed headers — can rewrite `reply_to` and the
+HMAC will still verify. TLS to your webhook URL is the actual integrity
+layer for the envelope fields; the HMAC is defense-in-depth for proven
+origin and covers the body bytes. If you need byte-exact assurance for a
+specific field, re-parse it from `raw_message` (whose integrity
+`body_hash` *does* cover).
+
+**Also not guaranteed:** upstream-DKIM coverage of `Reply-To:`. If the
+original sender's DKIM signature did not sign `Reply-To` (whether
+because they didn't sign it, or there was no DKIM at all), a MITM
+between sender and e2a could have rewritten the header before it reached
+the relay. e2a does not re-verify or surface per-header DKIM coverage
+today — the `Authentication-Results` / SPF/DKIM surface is unchanged.
+For routing decisions where attacker-controlled `Reply-To` would matter,
+also confirm `email.is_verified` and that the sender's domain is one you
+expect.
+
+We chose to keep `reply_to` populated whenever it's present (rather than
+masking it on partially-trusted messages or exposing a `reply_to_signed`
+flag) so the field shape stays uniform with `to`/`cc` and consumers can
+make their own policy decision. The trust model is documented on the
+property docstring.
+
+### Wire change
+The webhook payload schema now includes an optional `reply_to: string[]`
+field. Existing consumers that ignore unknown fields are unaffected; older
+SDK versions parsing the same payload continue to work and simply do not
+see the new key.
+
+### Other generated-type additions
+The high-level surface above is what most consumers will touch. For users
+of `client.api.*` or `e2a.v1.generated.*` directly, the following backend
+endpoints / fields also landed since 2.2.0 and are reflected in the
+regenerated types:
+
+- Per-record DNS verification — separate MX / SPF / DKIM diagnostic
+  responses on the domain-verification endpoints.
+- Enriched `DashboardAgent` — `Inbound7d`, `Outbound7d`, `Pending`,
+  `LastDelivery`, `WebhookHealthy` fields on the dashboard list.
+- OAuth 2.1 authorization-server endpoints (fosite-backed) used by the
+  MCP server flow.
+- Per-domain DKIM key generation endpoint.
+- One-time signing-secret reveal on creation.
+- Pending-review polish — provenance, quoted-inbound, headers-preview,
+  draft-footer fields on the review payload.
+
+These are additive and don't break existing 2.2.0 callers.

{e2a-2.2.0 → e2a-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python SDK for the e2a protocol — email-to-agent authentication
 Project-URL: Homepage, https://e2a.dev
 Project-URL: Repository, https://github.com/Mnexa-AI/e2a
@@ -120,7 +120,7 @@ def webhook():
     return {"ok": True}
 ```
 
-Get a signing secret from the dashboard's Settings → Webhook signing secrets (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
+Get a signing secret from the dashboard's **Webhook secrets** page (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
 
 ## Raw vs high-level API
 
@@ -407,6 +407,7 @@ print(result.status, result.message_id)
 | `recipient` | `str` | Per-delivery target — your agent's address |
 | `to` | `list[str]` | Parsed `To:` header — every address from the original message |
 | `cc` | `list[str]` | Parsed `Cc:` header (empty when no CCs) |
+| `reply_to` | `list[str]` | Parsed `Reply-To:` header — empty when absent (never falls back to `sender`). Useful when `sender` is a no-reply notifications address (Granola, GitHub, etc.) and the real correspondent is in Reply-To. |
 | `subject` | `str` | Email subject line |
 | `text_body` | `str` | Plain-text email body |
 | `html_body` | `str \| None` | HTML email body, if present |
@@ -416,7 +417,7 @@ print(result.status, result.message_id)
 | `auth` | `AuthHeaders` | Full authentication details |
 | `raw_message` | `bytes` | Raw RFC 2822 email bytes |
 
-All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
+All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `reply_to`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
 
 **Methods:**
 

{e2a-2.2.0 → e2a-2.3.0}/README.md

@@ -86,7 +86,7 @@ def webhook():
     return {"ok": True}
 ```
 
-Get a signing secret from the dashboard's Settings → Webhook signing secrets (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
+Get a signing secret from the dashboard's **Webhook secrets** page (or `POST /api/v1/users/me/signing-secrets`). Set it as `E2A_WEBHOOK_SECRET` so `parse_webhook` picks it up automatically, or pass it explicitly: `client.parse_webhook(body, secret="whsec_...")`.
 
 ## Raw vs high-level API
 
@@ -373,6 +373,7 @@ print(result.status, result.message_id)
 | `recipient` | `str` | Per-delivery target — your agent's address |
 | `to` | `list[str]` | Parsed `To:` header — every address from the original message |
 | `cc` | `list[str]` | Parsed `Cc:` header (empty when no CCs) |
+| `reply_to` | `list[str]` | Parsed `Reply-To:` header — empty when absent (never falls back to `sender`). Useful when `sender` is a no-reply notifications address (Granola, GitHub, etc.) and the real correspondent is in Reply-To. |
 | `subject` | `str` | Email subject line |
 | `text_body` | `str` | Plain-text email body |
 | `html_body` | `str \| None` | HTML email body, if present |
@@ -382,7 +383,7 @@ print(result.status, result.message_id)
 | `auth` | `AuthHeaders` | Full authentication details |
 | `raw_message` | `bytes` | Raw RFC 2822 email bytes |
 
-All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
+All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `reply_to`, `subject`, `text_body`, `html_body`, `attachments`, `conversation_id`, `received_at`) are gated — accessing them on an unverified webhook payload raises `UnverifiedEmailError`. Always-available regardless of verification: `auth`, `raw_message`, `is_verified`, `verified`, `unverified_payload`. Emails returned by `client.get_message(...)` are pre-verified (the bearer token already authenticated the channel). `client.get_messages(...)` returns lightweight `MessageSummary` items, not `InboundEmail`, so the gate doesn't apply.
 
 **Methods:**
 

{e2a-2.2.0 → e2a-2.3.0}/codegen-requirements.txt

@@ -12,11 +12,11 @@ isort==8.0.1
 more-itertools==10.8.0
 mypy_extensions==1.1.0
 packaging==26.2
-pathspec==1.1.0
+pathspec==1.1.1
 platformdirs==4.9.4
-pydantic==2.13.3
-pydantic_core==2.46.3
+pydantic==2.13.4
+pydantic_core==2.46.4
 pytokens==0.4.1
-typeguard==4.5.1
+typeguard==4.5.2
 typing-inspection==0.4.2
 typing_extensions==4.15.0

{e2a-2.2.0 → e2a-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "2.2.0"
+version = "2.3.0"
 description = "Python SDK for the e2a protocol — email-to-agent authentication"
 readme = "README.md"
 license = "Apache-2.0"

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/api.py

@@ -11,6 +11,7 @@ see :class:`e2a.v1.client.E2AClient`.
 from __future__ import annotations
 
 import os
+import uuid
 from typing import Optional
 from urllib.parse import quote
 
@@ -59,6 +60,19 @@ def _check_response(resp: httpx.Response) -> None:
         raise E2AApiError(resp.status_code, message)
 
 
+def _idempotency_header(idempotency_key: Optional[str]) -> dict:
+    """Build the ``Idempotency-Key`` header for a side-effectful send.
+
+    A caller-supplied key is passed through verbatim. When ``None``, a
+    fresh UUIDv4 is generated so callers get retry-safe transport
+    behavior by default. To benefit across an explicit retry loop the
+    caller must supply a stable key (the per-call default does not
+    survive retries — each call would mint a new UUID).
+    """
+    key = idempotency_key if idempotency_key is not None else uuid.uuid4().hex
+    return {"Idempotency-Key": key}
+
+
 def _encode_email(email: str) -> str:
     """URL-encode an email for use in path segments."""
     return quote(email, safe="")
@@ -200,18 +214,25 @@ class E2AApi:
         agent_email: str,
         message_id: str,
         body: ReplyToMessageRequest,
+        idempotency_key: Optional[str] = None,
     ) -> SendEmailResponse:
         resp = self._client.post(
             f"/api/v1/agents/{_encode_email(agent_email)}/messages/{message_id}/reply",
             json=body.model_dump(by_alias=True, exclude_none=True),
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return SendEmailResponse.model_validate(resp.json())
 
-    def send_email(self, body: SendEmailRequest) -> SendEmailResponse:
+    def send_email(
+        self,
+        body: SendEmailRequest,
+        idempotency_key: Optional[str] = None,
+    ) -> SendEmailResponse:
         resp = self._client.post(
             "/api/v1/send",
             json=body.model_dump(by_alias=True, exclude_none=True),
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return SendEmailResponse.model_validate(resp.json())

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/async_client.py

@@ -19,7 +19,7 @@ import httpx
 if TYPE_CHECKING:
     from e2a.v1.websocket import WSNotification
 
-from e2a.v1.api import E2AApiError, _check_response
+from e2a.v1.api import E2AApiError, _check_response, _idempotency_header
 from e2a.v1.generated import (
     Agent,
     ApprovePendingMessageRequest,
@@ -187,18 +187,25 @@ class AsyncE2AApi:
         agent_email: str,
         message_id: str,
         body: ReplyToMessageRequest,
+        idempotency_key: Optional[str] = None,
     ) -> SendEmailResponse:
         resp = await self._client.post(
             f"/api/v1/agents/{_encode_email(agent_email)}/messages/{message_id}/reply",
             json=body.model_dump(by_alias=True, exclude_none=True),
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return SendEmailResponse.model_validate(resp.json())
 
-    async def send_email(self, body: SendEmailRequest) -> SendEmailResponse:
+    async def send_email(
+        self,
+        body: SendEmailRequest,
+        idempotency_key: Optional[str] = None,
+    ) -> SendEmailResponse:
         resp = await self._client.post(
             "/api/v1/send",
             json=body.model_dump(by_alias=True, exclude_none=True),
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return SendEmailResponse.model_validate(resp.json())
@@ -394,6 +401,7 @@ class AsyncE2AClient:
                 recipient=m.recipient or "",
                 to=list(m.to or []),
                 cc=list(m.cc or []),
+                reply_to=list(m.reply_to or []),
                 subject=m.subject or "",
                 status=m.status or "",
                 created_at=m.created_at or "",
@@ -415,8 +423,15 @@ class AsyncE2AClient:
         conversation_id: Optional[str] = None,
         attachments: Optional[list[Attachment]] = None,
         agent_email: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> SendResult:
-        """Reply to an inbound email."""
+        """Reply to an inbound email.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Supply a stable key derived from the triggering event (e.g. the
+        inbound message id) to make this reply safe to retry; omit to
+        let the SDK generate a fresh UUIDv4 per call.
+        """
         email = self._require_agent_email(agent_email)
         req = ReplyToMessageRequest(
             body=body,
@@ -427,7 +442,7 @@ class AsyncE2AClient:
             conversation_id=conversation_id,
             attachments=_serialize_attachments(attachments),
         )
-        resp = await self.api.reply_to_message(email, message_id, req)
+        resp = await self.api.reply_to_message(email, message_id, req, idempotency_key=idempotency_key)
         return SendResult(
             status=resp.status or "",
             message_id=resp.message_id or "",
@@ -445,8 +460,15 @@ class AsyncE2AClient:
         conversation_id: Optional[str] = None,
         attachments: Optional[list[Attachment]] = None,
         agent_email: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> SendResult:
-        """Send a new email."""
+        """Send a new email.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Supply a stable key derived from the triggering event (e.g. a
+        job id) to make this send safe to retry; omit to let the SDK
+        generate a fresh UUIDv4 per call.
+        """
         email = self._require_agent_email(agent_email)
         req = SendEmailRequest(
             to=to,
@@ -459,7 +481,7 @@ class AsyncE2AClient:
             conversation_id=conversation_id,
             attachments=_serialize_attachments(attachments),
         )
-        resp = await self.api.send_email(req)
+        resp = await self.api.send_email(req, idempotency_key=idempotency_key)
         return SendResult(
             status=resp.status or "",
             message_id=resp.message_id or "",

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/client.py

@@ -197,6 +197,7 @@ class E2AClient:
                 recipient=m.recipient or "",
                 to=list(m.to or []),
                 cc=list(m.cc or []),
+                reply_to=list(m.reply_to or []),
                 subject=m.subject or "",
                 status=m.status or "",
                 created_at=m.created_at or "",
@@ -218,8 +219,16 @@ class E2AClient:
         conversation_id: Optional[str] = None,
         attachments: Optional[list[Attachment]] = None,
         agent_email: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> SendResult:
-        """Reply to an inbound email."""
+        """Reply to an inbound email.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Supply a stable key derived from the triggering event (e.g. the
+        inbound message id) to make this reply safe to retry; omit to
+        let the SDK generate a fresh UUIDv4 per call (network-layer
+        retry safety only).
+        """
         email = self._require_agent_email(agent_email)
         req = ReplyToMessageRequest(
             body=body,
@@ -230,7 +239,7 @@ class E2AClient:
             conversation_id=conversation_id,
             attachments=_serialize_attachments(attachments),
         )
-        resp = self.api.reply_to_message(email, message_id, req)
+        resp = self.api.reply_to_message(email, message_id, req, idempotency_key=idempotency_key)
         return SendResult(
             status=resp.status or "",
             message_id=resp.message_id or "",
@@ -248,8 +257,16 @@ class E2AClient:
         conversation_id: Optional[str] = None,
         attachments: Optional[list[Attachment]] = None,
         agent_email: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> SendResult:
-        """Send a new email."""
+        """Send a new email.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Supply a stable key derived from the triggering event (e.g. a
+        job id) to make this send safe to retry; omit to let the SDK
+        generate a fresh UUIDv4 per call (network-layer retry safety
+        only — does not help across an explicit retry loop).
+        """
         email = self._require_agent_email(agent_email)
         req = SendEmailRequest(
             to=to,
@@ -262,7 +279,7 @@ class E2AClient:
             conversation_id=conversation_id,
             attachments=_serialize_attachments(attachments),
         )
-        resp = self.api.send_email(req)
+        resp = self.api.send_email(req, idempotency_key=idempotency_key)
         return SendResult(
             status=resp.status or "",
             message_id=resp.message_id or "",

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/generated/__init__.py

@@ -76,6 +76,7 @@ class DNSRecords(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
     )
+    dkim: DNSRecord | None = None
     mx: DNSRecord | None = None
     txt: DNSRecord | None = None
 
@@ -88,6 +89,9 @@ class DeleteUserDataResult(BaseModel):
     api_keys_deleted: int | None = None
     domains_deleted: int | None = None
     messages_deleted: int | None = None
+    oauth_access_tokens_deleted: int | None = None
+    oauth_auth_codes_deleted: int | None = None
+    oauth_refresh_tokens_deleted: int | None = None
     sessions_deleted: int | None = None
     usage_events_deleted: int | None = None
     usage_summaries_deleted: int | None = None
@@ -119,9 +123,21 @@ class Domain(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
     )
+    agent_count: int | None = Field(
+        None,
+        description='AgentCount is populated by list endpoints. Single-domain endpoints\n(register, verify) leave it zero — the count would require an\nextra query that callers can derive from the agents list anyway.',
+    )
     created_at: str | None = None
     dns_records: DNSRecords | None = None
     domain: str | None = Field(None, examples=['yourdomain.com'])
+    is_primary: bool | None = Field(
+        None,
+        description='IsPrimary marks the user\'s default domain — at most one per\nuser, enforced server-side via SetDomainPrimary. The redesign\'s\nDomains list renders this as a "Primary" chip.',
+    )
+    last_checked_at: str | None = Field(
+        None,
+        description='LastCheckedAt is the timestamp of the most recent\n/api/v1/domains/{domain}/verify probe (success or failure).\nDistinct from VerifiedAt, which only updates on success.',
+    )
     verification_token: str | None = Field(None, examples=['e2a-verify=abc123'])
     verified: bool | None = None
     verified_at: str | None = None
@@ -153,6 +169,7 @@ class MessageDetail(BaseModel):
     message_id: str | None = Field(None, examples=['msg_abc123'])
     raw_message: str | None = None
     recipient: str | None = Field(None, examples=['my-bot@example.com'])
+    reply_to: list[str] | None = None
     status: str | None = Field(None, examples=['read'])
     subject: str | None = Field(None, examples=['Hello'])
     to: list[str] | None = Field(None, examples=[['my-bot@example.com']])
@@ -165,12 +182,58 @@ class MessageSummary(BaseModel):
     cc: list[str] | None = None
     conversation_id: str | None = None
     created_at: str | None = Field(None, examples=['2025-01-15T10:30:00Z'])
+    direction: Literal['inbound', 'outbound'] | None = Field(None, examples=['inbound'])
     from_: str | None = Field(None, alias='from', examples=['alice@example.com'])
+    hitl_status: (
+        Literal[
+            'pending_approval',
+            'sent',
+            'rejected',
+            'expired_approved',
+            'expired_rejected',
+        ]
+        | None
+    ) = Field(None, examples=['sent'])
     message_id: str | None = Field(None, examples=['msg_abc123'])
     recipient: str | None = Field(None, examples=['my-bot@example.com'])
-    status: Literal['unread', 'read'] | None = Field(None, examples=['unread'])
+    reply_to: list[str] | None = None
+    size_bytes: int | None = Field(None, examples=[4231])
+    status: str | None = Field(
+        None,
+        description='Status carries the inbound inbox_status value (`unread` | `read`).\nEmpty string for outbound rows — clients filtering on Status must\ngate on `Direction == "inbound"` first. The enum was removed from\nthe swag annotation deliberately so SDK generators don\'t emit a\n`Literal["unread", "read"]` that breaks at runtime.',
+    )
     subject: str | None = Field(None, examples=['Hello'])
     to: list[str] | None = Field(None, examples=[['my-bot@example.com']])
+    webhook_error: str | None = None
+    webhook_status: Literal['pending', 'delivered', 'failed'] | None = Field(
+        None, examples=['delivered']
+    )
+
+
+class OAuthConnectionEntry(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    agent_email: str | None = None
+    client_id: str | None = None
+    client_name: str | None = None
+    expires_at: str | None = None
+    issued_at: str | None = None
+    revoked_at: str | None = None
+    scope: str | None = None
+
+
+class PendingMessageInboundContext(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    auth_headers: dict[str, str] | None = Field(
+        None,
+        description='AuthHeaders carries the SPF/DKIM/DMARC validation results captured\nat inbound time. Keys are conventionally "spf", "dkim", "dmarc"\neach with values "pass" | "fail" | "neutral" | etc. The dashboard\nrenders these as found/missing chips on the provenance pane.',
+    )
+    created_at: str | None = Field(None, examples=['2025-01-15T10:25:00Z'])
+    sender: str | None = Field(None, examples=['alice@gmail.com'])
+    subject: str | None = Field(None, examples=['contract details'])
 
 
 class PendingMessageSummary(BaseModel):
@@ -261,6 +324,7 @@ class SigningSecretSummary(BaseModel):
     id: str | None = None
     last_signed_at: str | None = None
     name: str | None = None
+    secret: str | None = None
     secret_prefix: str | None = None
 
 
@@ -275,6 +339,13 @@ class UpdateAgentRequest(BaseModel):
     webhook_url: str | None = None
 
 
+class UpdateDomainRequest(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    is_primary: bool | None = None
+
+
 class UsageEventEntry(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
@@ -301,7 +372,22 @@ class VerifyDomainResponse(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
     )
+    dkim: Literal['found', 'missing', 'deferred'] | None = Field(
+        None,
+        description='DKIM status: "found" iff the published TXT record at\n"{selector}._domainkey.{domain}" matches the per-domain public\nkey stored at registration time. "missing" iff a keypair is\nstored but the TXT record isn\'t published yet. "deferred" iff\nno keypair is stored — pre-migration rows that haven\'t been\nre-claimed since #5 shipped. A fresh-claimed domain always has\na keypair, so "deferred" only appears on legacy data.',
+        examples=['found'],
+    )
     domain: str | None = Field(None, examples=['yourdomain.com'])
+    mx: Literal['found', 'missing'] | None = Field(
+        None,
+        description='MX status: "found" iff at least one MX record points at the\ndeployment\'s smtp domain. "missing" otherwise.',
+        examples=['found'],
+    )
+    spf: Literal['found', 'missing'] | None = Field(
+        None,
+        description='SPF status: "found" iff a v=spf1 TXT record includes the\ndeployment\'s send domain. "missing" otherwise.',
+        examples=['found'],
+    )
     verified: bool | None = None
     verified_at: str | None = None
 
@@ -358,10 +444,24 @@ class PendingMessageDetail(BaseModel):
     edited: bool | None = None
     email_message_id: str | None = Field(None, examples=['<orig@gmail.com>'])
     id: str | None = Field(None, examples=['msg_abc123'])
+    inbound: PendingMessageInboundContext | None = Field(
+        None,
+        description='InboundContext is attached when this is a reply — provides the\nSPF/DKIM/DMARC provenance + sender/subject of the inbound message\nbeing replied to so the review panel can render the context pane.',
+    )
     method: str | None = Field(None, examples=['smtp'])
     provider_message_id: str | None = None
     rejection_reason: str | None = None
     reviewed_at: str | None = Field(None, examples=['2025-01-15T10:35:00Z'])
+    reviewed_by_name: str | None = Field(
+        None,
+        description="ReviewedByName is the JOIN'd display name from the reviewer's\nusers row. NULL when reviewed_by_user_id is null (worker) or when\nthe reviewer's user account has since been deleted (the FK has\nON DELETE SET NULL specifically so this doesn't poison the audit\ntrail).",
+        examples=['Jamie'],
+    )
+    reviewed_by_user_id: str | None = Field(
+        None,
+        description='ReviewedByUserID identifies the human reviewer for approved or\nrejected messages. NULL on TTL-expired transitions (worker\nauto-approve / auto-reject) where no human reviewed the message.',
+        examples=['usr_abc123'],
+    )
     status: (
         Literal[
             'sent',
@@ -416,6 +516,7 @@ class UserExport(BaseModel):
     domains: list[github_com_Mnexa_AI_e2a_internal_identity.Domain] | None = None
     generated_at: str | None = None
     messages: list[github_com_Mnexa_AI_e2a_internal_identity.Message] | None = None
+    oauth_connections: list[OAuthConnectionEntry] | None = None
     schema_version: str | None = None
     usage_events: list[UsageEventEntry] | None = None
     user: UserExportUser | None = None

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/generated/_internal.py

@@ -126,6 +126,7 @@ class MessageDetail(BaseModel):
     from_: str | None = Field(None, alias='from', examples=['alice@example.com'])
     message_id: str | None = Field(None, examples=['msg_abc123'])
     raw_message: str | None = None
+    reply_to: list[str] | None = None
     status: str | None = Field(None, examples=['read'])
     subject: str | None = Field(None, examples=['Hello'])
     to: str | None = Field(None, examples=['my-bot@example.com'])
@@ -139,6 +140,7 @@ class MessageSummary(BaseModel):
     created_at: str | None = Field(None, examples=['2025-01-15T10:30:00Z'])
     from_: str | None = Field(None, alias='from', examples=['alice@example.com'])
     message_id: str | None = Field(None, examples=['msg_abc123'])
+    reply_to: list[str] | None = None
     status: Literal['unread', 'read'] | None = Field(None, examples=['unread'])
     subject: str | None = Field(None, examples=['Hello'])
     to: str | None = Field(None, examples=['my-bot@example.com'])

e2a-2.3.0/src/e2a/v1/generated/github_com_Mnexa_AI_e2a_internal_identity.py

@@ -0,0 +1,127 @@
+# generated by datamodel-codegen:
+#   filename:  e2a-openapi3.yaml
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AgentIdentity(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    agent_mode: str | None = None
+    created_at: str | None = None
+    domain: str | None = None
+    domain_verified: bool | None = None
+    email: str | None = None
+    hitl_enabled: bool | None = None
+    hitl_expiration_action: str | None = None
+    hitl_ttl_seconds: int | None = None
+    id: str | None = None
+    inbound_7d: int | None = Field(
+        None,
+        description='Dashboard enrichment fields. Computed at read\ntime by ListAgentsByUser via correlated subqueries — other load\npaths (GetAgentByID / GetAgentByEmail) leave them at zero values,\nsame pattern as Domain.AgentCount. Switch to denormalized columns\nif the read cost ever bites.',
+    )
+    last_delivery_at: str | None = None
+    name: str | None = None
+    outbound_7d: int | None = None
+    pending_count: int | None = None
+    public: bool | None = None
+    user_id: str | None = None
+    webhook_healthy: bool | None = Field(
+        None,
+        description="WebhookHealthy is false iff there's been a failed webhook delivery\nin the last 24h. Defaults to true for agents with no deliveries\nyet — avoids painting fresh agents red. Meaningless for\nagent_mode='local'; the frontend hides the badge in that case.",
+    )
+    webhook_url: str | None = None
+
+
+class Domain(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    agent_count: int | None = Field(
+        None,
+        description='AgentCount is computed at read time by ListDomainsByUser and is\nnot a persisted column. Single-domain LookupDomain leaves it at\nthe zero value — callers that need the count call the list path\n(this column-versus-aggregate split avoids changing every store\nsignature to thread an agent-counter through).',
+    )
+    created_at: str | None = None
+    dkim_public_key: str | None = None
+    dkim_selector: str | None = Field(
+        None,
+        description="DKIM keypair fields. The selector + public key\nare user-facing — the dashboard shows them so users can copy the\nDNS TXT record. The private key is intentionally NOT in the JSON\nshape; it's only read by the outbound signer via\nGetDKIMKey(domain). Domains created before migration 014 ran\nkeep all three NULL until the next ClaimOrCreate or backfill.",
+    )
+    domain: str | None = None
+    is_primary: bool | None = Field(
+        None,
+        description="IsPrimary marks the user's default domain. At most one TRUE per\nuser (enforced by a partial unique index in migration 013).",
+    )
+    last_checked_at: str | None = Field(
+        None,
+        description='LastCheckedAt is updated whenever the verification probe runs,\nsuccessful or not. NULL until the first probe — distinct from\n"probed and failed" which is captured by `verified=false` + a\nnon-null LastCheckedAt.',
+    )
+    user_id: str | None = None
+    verification_token: str | None = None
+    verified: bool | None = None
+    verified_at: str | None = None
+
+
+class Message(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    agent_id: str | None = None
+    approval_expires_at: str | None = None
+    attachments: list[int] | None = None
+    auth_headers: dict[str, str] | None = None
+    bcc: list[str] | None = None
+    body_html: str | None = None
+    body_text: str | None = None
+    cc: list[str] | None = None
+    conversation_id: str | None = None
+    created_at: str | None = None
+    delivery_status: str | None = None
+    direction: str | None = None
+    edited: bool | None = None
+    email_message_id: str | None = None
+    expires_at: str | None = None
+    id: str | None = None
+    inbox_status: str | None = Field(
+        None,
+        description="InboxStatus mirrors messages.inbox_status ('unread' | 'read') for\ninbound rows. Kept separate from DeliveryStatus (which currently\ncarries the same value under a confusing JSON key — see line 161)\nso the dashboard's inbox can read it under a non-overloaded key.\nEmpty on outbound rows. Populated by GetMessagesByAgent.",
+    )
+    method: str | None = None
+    provider_message_id: str | None = None
+    raw_message: list[int] | None = None
+    recipient: str | None = None
+    rejection_reason: str | None = None
+    reply_to: list[str] | None = Field(
+        None,
+        description='ReplyTo is the parsed Reply-To: header on inbound messages — empty\nwhen the header was absent. Distinct from Sender so consumers can\nrecover the original From: of forwarded / notification mail whose\nReply-To points at a different mailbox. Outbound-irrelevant.',
+    )
+    reviewed_at: str | None = None
+    reviewed_by_name: str | None = Field(
+        None,
+        description="ReviewedByName is the JOIN'd display name from the reviewer's\nusers row, populated only by GetOutboundMessageForUser. List\nendpoints leave this empty to avoid a join-per-row cost — the\npending-detail page is where reviewer attribution matters.",
+    )
+    reviewed_by_user_id: str | None = Field(
+        None,
+        description='ReviewedByUserID identifies the human reviewer who approved or\nrejected this message. NULL on worker-triggered transitions\n(TTL auto-approve / auto-reject) — operator-visible signal "no\nhuman looked at this." Set by ApproveAndSend and RejectPending,\nleft null by ExpireApproveAndSend / ExpireReject.',
+    )
+    sender: str | None = None
+    size_bytes: int | None = Field(
+        None,
+        description='SizeBytes is the byte length of raw_message. Populated by load paths\nthat compute it (e.g. GetMessagesByAgent for the dashboard inbox).\nZero on load paths that don\'t — the inbox renders "—" in that case.',
+    )
+    status: str | None = Field(
+        None,
+        description="HITL approval fields. Status defaults to 'sent'; body and attachments\nare populated only while a message is in 'pending_approval', and are\nscrubbed on any terminal transition.",
+    )
+    subject: str | None = None
+    to_recipients: list[str] | None = Field(
+        None,
+        description='Multi-recipient fields. For outbound, these are the addressed\nTo/Cc/Bcc recipients of the send. For inbound, ToRecipients and CC\nare the parsed To: and Cc: headers of the original message (the\nper-delivery target for this row is in Recipient). BCC is\noutbound-only.',
+    )
+    type: str | None = None
+    webhook_attempts: int | None = None
+    webhook_error: str | None = None
+    webhook_status: str | None = None

{e2a-2.2.0 → e2a-2.3.0}/src/e2a/v1/handler.py

@@ -12,7 +12,7 @@ import email as email_lib
 import hashlib
 import hmac
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
 from email.policy import default as default_policy
 from typing import TYPE_CHECKING, Any, Optional
@@ -193,6 +193,10 @@ class MessageSummary:
     subject: str
     status: str  # "unread" or "read"
     created_at: str
+    # Added after the initial release; defaulted to [] so existing
+    # positional constructors (test fixtures, custom adapters) keep
+    # working without shifting the trailing args.
+    reply_to: list[str] = field(default_factory=list)
 
 
 @dataclass
@@ -242,8 +246,8 @@ class InboundEmail:
         - :attr:`verified` — has verify_signature succeeded yet?
 
     Gated (require verify_signature first):
-        message_id, conversation_id, sender, recipient, to, cc, subject,
-        text_body, html_body, attachments, received_at, reply().
+        message_id, conversation_id, sender, recipient, to, cc, reply_to,
+        subject, text_body, html_body, attachments, received_at, reply().
     """
 
     def __init__(
@@ -263,6 +267,10 @@ class InboundEmail:
         received_at: Optional[str],
         raw_message: bytes,
         client: E2AClient,
+        # Added after the initial release; defaulted to None so existing
+        # constructors keep working. Normalized to [] below to match the
+        # SDK contract that reply_to is always a list, never None.
+        reply_to: Optional[list[str]] = None,
     ) -> None:
         # Stored as private fields. Public access flows through @property
         # gates that check self._verified. The constructor takes the
@@ -273,6 +281,7 @@ class InboundEmail:
         self._recipient = recipient
         self._to = to
         self._cc = cc
+        self._reply_to = reply_to if reply_to is not None else []
         self._subject = subject
         self._text_body = text_body
         self._html_body = html_body
@@ -329,6 +338,7 @@ class InboundEmail:
             "recipient": self._recipient,
             "to": list(self._to),
             "cc": list(self._cc),
+            "reply_to": list(self._reply_to),
             "subject": self._subject,
             "text_body": self._text_body,
             "html_body": self._html_body,
@@ -419,6 +429,47 @@ class InboundEmail:
         self._require_verified()
         return self._cc
 
+    @property
+    def reply_to(self) -> list[str]:
+        """Parsed Reply-To: header — addresses the sender wants replies sent to.
+
+        Empty list when the header was absent (the SDK never silently falls
+        back to :attr:`sender`; that decision belongs to the caller).
+        Distinct from :attr:`sender` so consumers can recover the original
+        From: address of forwarded / notification mail whose Reply-To
+        points at a different mailbox.
+
+        .. warning::
+           Trust path is weaker than you might assume. The HMAC binds a
+           fixed set of auth headers (sender, timestamp, message_id,
+           body_hash, …) and ``body_hash = SHA-256(raw_message)``. It
+           does **not** sign the JSON envelope, and the SDK reads this
+           field from the JSON envelope — not from ``raw_message``. So
+           ``reply_to`` here is trusted on the same terms as :attr:`to`,
+           :attr:`cc`, :attr:`recipient`, :attr:`subject`, and the body
+           fields: the server placed it in the JSON, TLS protected the
+           wire to your webhook URL, and you trust your relay-to-webhook
+           connection. The HMAC alone does not prevent an attacker who
+           can modify the JSON envelope after signing from rewriting
+           ``reply_to`` while ``verify_signature`` still returns
+           ``True``.
+
+           If you need byte-exact integrity (e.g. routing decisions
+           where an attacker who can break TLS would matter), re-parse
+           the ``Reply-To:`` header from :attr:`raw_message` yourself —
+           that bytes-level integrity *is* covered by ``body_hash``.
+
+           Separately, this is **not** an upstream-DKIM coverage check.
+           If the original sender's DKIM signature did not cover
+           Reply-To (whether because they did not sign it, or there was
+           no DKIM at all), a MITM between sender and e2a could have
+           rewritten the header before it reached the relay. For
+           high-stakes routing, also confirm :attr:`is_verified` and
+           that the sender's domain is one you expect.
+        """
+        self._require_verified()
+        return self._reply_to
+
     @property
     def subject(self) -> str:
         self._require_verified()
@@ -593,6 +644,9 @@ def _parse_payload(data: dict[str, Any]) -> dict[str, Any]:
         "recipient": data.get("recipient", ""),
         "to": list(data.get("to") or []),
         "cc": list(data.get("cc") or []),
+        # reply_to comes from the server's parse of the Reply-To: header.
+        # Empty list when absent — the server never falls back to From:.
+        "reply_to": list(data.get("reply_to") or []),
         "subject": subject or data.get("subject", ""),
         "text_body": text_body,
         "html_body": html_body,
@@ -649,6 +703,9 @@ class AsyncInboundEmail:
         received_at: Optional[str],
         raw_message: bytes,
         client: AsyncE2AClient,
+        # See InboundEmail.__init__ for the rationale on positioning
+        # reply_to last with a None default.
+        reply_to: Optional[list[str]] = None,
     ) -> None:
         self._message_id = message_id
         self._conversation_id = conversation_id
@@ -656,6 +713,7 @@ class AsyncInboundEmail:
         self._recipient = recipient
         self._to = to
         self._cc = cc
+        self._reply_to = reply_to if reply_to is not None else []
         self._subject = subject
         self._text_body = text_body
         self._html_body = html_body
@@ -695,6 +753,7 @@ class AsyncInboundEmail:
             "recipient": self._recipient,
             "to": list(self._to),
             "cc": list(self._cc),
+            "reply_to": list(self._reply_to),
             "subject": self._subject,
             "text_body": self._text_body,
             "html_body": self._html_body,
@@ -755,6 +814,47 @@ class AsyncInboundEmail:
         self._require_verified()
         return self._cc
 
+    @property
+    def reply_to(self) -> list[str]:
+        """Parsed Reply-To: header — addresses the sender wants replies sent to.
+
+        Empty list when the header was absent (the SDK never silently falls
+        back to :attr:`sender`; that decision belongs to the caller).
+        Distinct from :attr:`sender` so consumers can recover the original
+        From: address of forwarded / notification mail whose Reply-To
+        points at a different mailbox.
+
+        .. warning::
+           Trust path is weaker than you might assume. The HMAC binds a
+           fixed set of auth headers (sender, timestamp, message_id,
+           body_hash, …) and ``body_hash = SHA-256(raw_message)``. It
+           does **not** sign the JSON envelope, and the SDK reads this
+           field from the JSON envelope — not from ``raw_message``. So
+           ``reply_to`` here is trusted on the same terms as :attr:`to`,
+           :attr:`cc`, :attr:`recipient`, :attr:`subject`, and the body
+           fields: the server placed it in the JSON, TLS protected the
+           wire to your webhook URL, and you trust your relay-to-webhook
+           connection. The HMAC alone does not prevent an attacker who
+           can modify the JSON envelope after signing from rewriting
+           ``reply_to`` while ``verify_signature`` still returns
+           ``True``.
+
+           If you need byte-exact integrity (e.g. routing decisions
+           where an attacker who can break TLS would matter), re-parse
+           the ``Reply-To:`` header from :attr:`raw_message` yourself —
+           that bytes-level integrity *is* covered by ``body_hash``.
+
+           Separately, this is **not** an upstream-DKIM coverage check.
+           If the original sender's DKIM signature did not cover
+           Reply-To (whether because they did not sign it, or there was
+           no DKIM at all), a MITM between sender and e2a could have
+           rewritten the header before it reached the relay. For
+           high-stakes routing, also confirm :attr:`is_verified` and
+           that the sender's domain is one you expect.
+        """
+        self._require_verified()
+        return self._reply_to
+
     @property
     def subject(self) -> str:
         self._require_verified()

e2a-2.3.0/tests/test_idempotency.py

@@ -0,0 +1,130 @@
+"""Tests for the Idempotency-Key transport behavior in the Python SDK."""
+
+import re
+
+import pytest
+
+from e2a.v1.api import E2AApi
+from e2a.v1.client import E2AClient
+from e2a.v1.generated import ReplyToMessageRequest, SendEmailRequest
+
+
+BASE = "https://e2a.dev"
+
+UUIDV4_RE = re.compile(
+    r"^[0-9a-f]{32}$|^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+
+def test_send_email_auto_generates_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/send",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_abc", "method": "smtp"},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.send_email(
+            SendEmailRequest(to=["alice@example.com"], subject="x", body="y")
+        )
+
+    req = httpx_mock.get_request()
+    key = req.headers["Idempotency-Key"]
+    assert key, "Idempotency-Key header not set"
+    assert UUIDV4_RE.match(key), f"key {key!r} is not a UUIDv4 hex/canonical shape"
+
+
+def test_send_email_honors_caller_supplied_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/send",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_abc", "method": "smtp"},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.send_email(
+            SendEmailRequest(to=["alice@example.com"], subject="x", body="y"),
+            idempotency_key="user-supplied-key-42",
+        )
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "user-supplied-key-42"
+
+
+def test_reply_to_message_carries_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/agents/bot%40test.dev/messages/msg_in_xyz/reply",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_out_xyz", "method": "smtp"},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.reply_to_message(
+            "bot@test.dev",
+            "msg_in_xyz",
+            ReplyToMessageRequest(body="hi"),
+            idempotency_key="reply-key-1",
+        )
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "reply-key-1"
+
+
+def test_send_email_generates_different_key_each_call(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/send",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_a", "method": "smtp"},
+    )
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/send",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_b", "method": "smtp"},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.send_email(SendEmailRequest(to=["a@b.com"], subject="x", body="y"))
+        api.send_email(SendEmailRequest(to=["a@b.com"], subject="x", body="y"))
+
+    reqs = httpx_mock.get_requests()
+    keys = [r.headers["Idempotency-Key"] for r in reqs]
+    assert len(keys) == 2
+    assert keys[0] != keys[1], "auto-generated keys should differ per call"
+
+
+def test_high_level_client_send_threads_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/send",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_xyz", "method": "smtp"},
+    )
+
+    with E2AClient(
+        api_key="e2a_test", agent_email="bot@test.dev"
+    ) as client:
+        client.send(
+            ["alice@example.com"],
+            "x",
+            "y",
+            idempotency_key="client-key-99",
+        )
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "client-key-99"
+
+
+def test_high_level_client_reply_threads_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/agents/bot%40test.dev/messages/msg_in_abc/reply",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_out_abc", "method": "smtp"},
+    )
+
+    with E2AClient(
+        api_key="e2a_test", agent_email="bot@test.dev"
+    ) as client:
+        client.reply("msg_in_abc", "hi", idempotency_key="client-reply-key")
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "client-reply-key"

{e2a-2.2.0 → e2a-2.3.0}/tests/test_v1_handler.py

@@ -198,6 +198,94 @@ def test_build_inbound_email_uses_structured_to_cc():
     assert email.recipient == "bot@agent.example.com"
 
 
+# ── reply_to (server-parsed Reply-To: header) ─────────────────────
+
+
+def test_reply_to_absent_is_empty_list():
+    """No Reply-To header → reply_to is [], never falls back to sender.
+
+    Callers decide whether to address replies to sender or somewhere else.
+    """
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    # _make_webhook_data does not set reply_to; the server would omit it too.
+    email = build_inbound_email(data, _mock_client(), trusted=True)
+    assert email.reply_to == []
+
+
+def test_reply_to_single_address():
+    """Most common case: notifications@foo with Reply-To: user@bar."""
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    data["reply_to"] = ["user@bar.com"]
+    email = build_inbound_email(data, _mock_client(), trusted=True)
+    assert email.reply_to == ["user@bar.com"]
+
+
+def test_reply_to_multi_address():
+    """RFC 5322 § 3.6.2 permits multiple addresses in Reply-To."""
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    data["reply_to"] = ["support@company.com", "ceo@company.com"]
+    email = build_inbound_email(data, _mock_client(), trusted=True)
+    assert email.reply_to == ["support@company.com", "ceo@company.com"]
+
+
+def test_reply_to_display_names_stripped_by_server():
+    """The SDK mirrors `to`/`cc`: it trusts the server's normalized list
+    (bare addresses, display names already stripped). This test pins the
+    contract — if the server sends bare addresses, the SDK surfaces them
+    unchanged."""
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    # Server would have sent ParseAddressList("Foo Bar" <foo@bar.com>) →
+    # ["foo@bar.com"]; the SDK does not re-parse.
+    data["reply_to"] = ["foo@bar.com"]
+    email = build_inbound_email(data, _mock_client(), trusted=True)
+    assert email.reply_to == ["foo@bar.com"]
+
+
+def test_reply_to_gated_until_verified():
+    """reply_to obeys the same UnverifiedEmailError gate as `to`/`cc` —
+    a webhook delivery is not safe to read until verify_signature() has
+    confirmed the HMAC."""
+    from e2a.v1 import UnverifiedEmailError
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    data["reply_to"] = ["user@bar.com"]
+    email = build_inbound_email(data, _mock_client())  # NOT trusted=True
+    with pytest.raises(UnverifiedEmailError):
+        _ = email.reply_to
+
+
+def test_reply_to_trusted_through_body_hash():
+    """The trust path for reply_to: e2a's HMAC binds SHA-256(raw_message),
+    and Reply-To is in raw_message bytes. Tampering with the structured
+    reply_to alone doesn't change body_hash, so the SDK trusts what the
+    server parses — same model as `to`/`cc`. This test pins the property:
+    a successfully-verified message exposes reply_to without re-parsing.
+    """
+    secret = "x" * 32
+    raw = b"From: notifications@example.com\r\nReply-To: real-user@example.com\r\nSubject: Hi\r\n\r\nbody"
+    email, _ = _signed_email(secret=secret, body=raw)
+    # The verified path: HMAC over body_hash succeeds → field access unlocks.
+    assert email.verify_signature(secret) is True
+    # _signed_email's fixture doesn't set reply_to in the JSON; this also
+    # confirms the safe default (empty) when the server didn't ship it.
+    assert email.reply_to == []
+
+
+def test_reply_to_in_unverified_payload():
+    """The escape hatch for inspecting unverified payloads also includes
+    reply_to so forensics can see what arrived without unlocking gates."""
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    data["reply_to"] = ["user@bar.com"]
+    email = build_inbound_email(data, _mock_client())  # unverified
+    payload = email.unverified_payload
+    assert payload["reply_to"] == ["user@bar.com"]
+
+
 # ── build_inbound_email ──────────────────────────────────────────
 
 

e2a-2.2.0/src/e2a/v1/generated/github_com_Mnexa_AI_e2a_internal_identity.py

@@ -1,79 +0,0 @@
-# generated by datamodel-codegen:
-#   filename:  e2a-openapi3.yaml
-
-from __future__ import annotations
-
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class AgentIdentity(BaseModel):
-    model_config = ConfigDict(
-        populate_by_name=True,
-    )
-    agent_mode: str | None = None
-    created_at: str | None = None
-    domain: str | None = None
-    domain_verified: bool | None = None
-    email: str | None = None
-    hitl_enabled: bool | None = None
-    hitl_expiration_action: str | None = None
-    hitl_ttl_seconds: int | None = None
-    id: str | None = None
-    name: str | None = None
-    public: bool | None = None
-    user_id: str | None = None
-    webhook_url: str | None = None
-
-
-class Domain(BaseModel):
-    model_config = ConfigDict(
-        populate_by_name=True,
-    )
-    created_at: str | None = None
-    domain: str | None = None
-    user_id: str | None = None
-    verification_token: str | None = None
-    verified: bool | None = None
-    verified_at: str | None = None
-
-
-class Message(BaseModel):
-    model_config = ConfigDict(
-        populate_by_name=True,
-    )
-    agent_id: str | None = None
-    approval_expires_at: str | None = None
-    attachments: list[int] | None = None
-    auth_headers: dict[str, str] | None = None
-    bcc: list[str] | None = None
-    body_html: str | None = None
-    body_text: str | None = None
-    cc: list[str] | None = None
-    conversation_id: str | None = None
-    created_at: str | None = None
-    delivery_status: str | None = None
-    direction: str | None = None
-    edited: bool | None = None
-    email_message_id: str | None = None
-    expires_at: str | None = None
-    id: str | None = None
-    method: str | None = None
-    provider_message_id: str | None = None
-    raw_message: list[int] | None = None
-    recipient: str | None = None
-    rejection_reason: str | None = None
-    reviewed_at: str | None = None
-    sender: str | None = None
-    status: str | None = Field(
-        None,
-        description="HITL approval fields. Status defaults to 'sent'; body and attachments\nare populated only while a message is in 'pending_approval', and are\nscrubbed on any terminal transition.",
-    )
-    subject: str | None = None
-    to_recipients: list[str] | None = Field(
-        None,
-        description='Multi-recipient fields. For outbound, these are the addressed\nTo/Cc/Bcc recipients of the send. For inbound, ToRecipients and CC\nare the parsed To: and Cc: headers of the original message (the\nper-delivery target for this row is in Recipient). BCC is\noutbound-only.',
-    )
-    type: str | None = None
-    webhook_attempts: int | None = None
-    webhook_error: str | None = None
-    webhook_status: str | None = None