e2a 2.1.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.1.0 → e2a-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.1.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:**
 
@@ -431,7 +432,7 @@ All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `t
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
 - `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.parse(body)` → `InboundEmail` — *deprecated since 2.2, removed in 3.0.* Accepts bytes, str, dict, or `MessageDetail` and returns an unverified email. Use `parse_webhook` for webhook handlers, or `email.unverified_payload` for inspection without verification. Calling `parse` emits a `DeprecationWarning`.
 - `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`

{e2a-2.1.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:**
 
@@ -397,7 +398,7 @@ All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `t
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
 - `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.parse(body)` → `InboundEmail` — *deprecated since 2.2, removed in 3.0.* Accepts bytes, str, dict, or `MessageDetail` and returns an unverified email. Use `parse_webhook` for webhook handlers, or `email.unverified_payload` for inspection without verification. Calling `parse` emits a `DeprecationWarning`.
 - `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`

{e2a-2.1.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.1.0 → e2a-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "2.1.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.1.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.1.0 → e2a-2.3.0}/src/e2a/v1/async_client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import base64
 import json
 import os
+import warnings
 from typing import TYPE_CHECKING, Any, AsyncIterator, Optional
 from urllib.parse import quote
 
@@ -18,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,
@@ -186,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())
@@ -306,13 +314,33 @@ class AsyncE2AClient:
     ) -> AsyncInboundEmail:
         """Parse a webhook payload into an AsyncInboundEmail.
 
+        .. deprecated:: 2.2
+           Use :meth:`parse_webhook` for webhook handlers (parse + verify
+           in one call) or :attr:`AsyncInboundEmail.unverified_payload`
+           for inspection without verification. ``parse`` will be removed
+           in 3.0.
+
         Synchronous (no I/O). The returned email's ``.reply()`` is async.
 
         Returns an *unverified* AsyncInboundEmail — claim fields raise
         :class:`UnverifiedEmailError` until you call
-        :meth:`AsyncInboundEmail.verify_signature`. For webhook handlers,
-        prefer :meth:`parse_webhook` which combines parse + verify.
+        :meth:`AsyncInboundEmail.verify_signature`.
         """
+        warnings.warn(
+            "AsyncE2AClient.parse() is deprecated and will be removed in 3.0. "
+            "For webhook handlers, use client.parse_webhook(body) — it "
+            "parses and HMAC-verifies in one call. For inspection without "
+            "verification, use email.unverified_payload after parse_webhook.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._parse_unverified(body)
+
+    def _parse_unverified(
+        self,
+        body: bytes | str | dict[str, Any] | MessageDetail,
+    ) -> AsyncInboundEmail:
+        """Internal parse without the deprecation warning."""
         if isinstance(body, MessageDetail):
             data = body.model_dump(by_alias=True)
         elif isinstance(body, dict):
@@ -334,7 +362,7 @@ class AsyncE2AClient:
         See :meth:`E2AClient.parse_webhook` — identical contract.
         Synchronous despite living on the async client (no I/O).
         """
-        email = self.parse(body)
+        email = self._parse_unverified(body)
         if not email.verify_signature(secret):
             raise PermissionError("HMAC signature verification failed")
         return email
@@ -373,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 "",
@@ -394,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,
@@ -406,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 "",
@@ -424,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,
@@ -438,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.1.0 → e2a-2.3.0}/src/e2a/v1/client.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import base64
 import json
 import os
+import warnings
 from typing import Any, Optional
 
 from e2a.v1.api import E2AApi
@@ -92,14 +93,39 @@ class E2AClient:
     ) -> InboundEmail:
         """Parse a webhook payload or MessageDetail into an InboundEmail.
 
+        .. deprecated:: 2.2
+           Use :meth:`parse_webhook` for webhook handlers (parse + verify
+           in one call) or :attr:`InboundEmail.unverified_payload` for
+           inspection without verification. ``parse`` will be removed in
+           3.0.
+
         Accepts bytes, JSON string, dict, or a generated MessageDetail.
 
         The returned InboundEmail starts in the *unverified* state —
-        property accesses (sender, subject, body, …) will raise
-        :class:`UnverifiedEmailError` until you call
-        :meth:`InboundEmail.verify_signature`. For webhook handlers,
-        prefer :meth:`parse_webhook` which combines parse + verify.
+        property accesses (sender, subject, body, …) raise
+        :class:`UnverifiedEmailError` until :meth:`InboundEmail.verify_signature`
+        succeeds. The combination of "looks usable" + "blows up on first
+        field access" is precisely the trap that motivated the deprecation;
+        ``parse_webhook`` raises immediately on bad signatures and returns
+        a ready-to-use object on success.
         """
+        warnings.warn(
+            "E2AClient.parse() is deprecated and will be removed in 3.0. "
+            "For webhook handlers, use client.parse_webhook(body) — it "
+            "parses and HMAC-verifies in one call. For inspection without "
+            "verification, use email.unverified_payload after parse_webhook.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._parse_unverified(body)
+
+    def _parse_unverified(
+        self,
+        body: bytes | str | dict[str, Any] | MessageDetail,
+    ) -> InboundEmail:
+        """Internal parse without the deprecation warning. ``parse_webhook``
+        delegates here so the recommended path doesn't emit the warning
+        meant for direct ``parse`` callers."""
         if isinstance(body, MessageDetail):
             data = body.model_dump(by_alias=True)
         elif isinstance(body, dict):
@@ -126,7 +152,7 @@ class E2AClient:
         ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
         variable (with ``E2A_HMAC_SECRET`` accepted as a deprecated alias).
         """
-        email = self.parse(body)
+        email = self._parse_unverified(body)
         if not email.verify_signature(secret):
             raise PermissionError("HMAC signature verification failed")
         return email
@@ -171,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 "",
@@ -192,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,
@@ -204,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 "",
@@ -222,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,
@@ -236,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 "",