e2a 2.2.0__tar.gz → 2.4.0__tar.gz

e2a-2.4.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## 2.4.0
+
+### Added
+- `idempotency_key` parameter on `E2AClient.approve_message()` and its
+  async counterpart (and on the lower-level `E2AApi.approve_message()`).
+  Approve fires a real SES send, so without a stable key a retry after
+  a transient failure could double-send. When supplied it's threaded
+  through as the `Idempotency-Key` header; when omitted the SDK mints
+  a fresh UUIDv4 per call — that gives network-layer retry safety only.
+  Supply a stable key derived from the review event (typically the
+  pending `message_id`) to dedupe across an explicit retry loop.
+- `sort`, `from_`, `subject_contains`, `conversation_id`, `since`,
+  `until` kwargs on `E2AApi.list_messages()` and the high-level
+  `E2AClient.get_messages()` (sync + async). `sort` defaults
+  server-side to newest-first; pass `"asc"` for FIFO polling. The
+  substring filters are case-insensitive and capped at 200 chars
+  server-side. `since` / `until` accept RFC3339 timestamps and
+  bracket `created_at`. Filter values are encoded into `next_token`,
+  so continuation requests must keep the same filter values.
+
+### Changed
+- **Default sort flipped to newest-first** on `GET /messages`. Prior
+  releases silently returned oldest-first for `direction=inbound` (the
+  SDK default) and newest-first for `direction=all`. A polling agent
+  that relied on FIFO drain order should now pass `sort="asc"` to
+  preserve the old behavior.
+- `agent_mode` is now a required field on `RegisterAgentRequest`. The
+  server previously silently defaulted to `"cloud"` and then 400'd
+  with a cryptic "webhook_url is required" message; it now explicitly
+  rejects requests missing `agent_mode` with a clear error. Pydantic
+  v2 will raise a validation error if you instantiate the request
+  without it. Set `agent_mode="local"` or `"cloud"` explicitly.
+
+## 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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.2.0
+Version: 2.4.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.4.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.4.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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "2.2.0"
+version = "2.4.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.4.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="")
@@ -177,8 +191,44 @@ class E2AApi:
         status: str = "unread",
         page_size: int = 50,
         token: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> ListMessagesResponse:
+        """List messages for an agent.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first).
+        Pass ``"asc"`` for FIFO polling — drain the inbox in arrival
+        order. The choice is encoded in ``next_token`` so subsequent
+        pages keep the same order; switching mid-pagination returns
+        400.
+
+        ``from_``, ``subject_contains``: case-insensitive substring
+        match (Postgres ILIKE). Capped server-side at 200 chars.
+
+        ``conversation_id``: exact match — narrow to one thread.
+
+        ``since`` / ``until``: RFC3339 timestamps (``datetime.isoformat()``
+        produces a valid value as long as it ends in ``Z`` or has a
+        timezone offset). Bracket on ``created_at`` (``>= since`` and
+        ``< until``).
+        """
         params: dict[str, str] = {"status": status, "page_size": str(page_size)}
+        if sort:
+            params["sort"] = sort
+        if from_:
+            params["from"] = from_
+        if subject_contains:
+            params["subject_contains"] = subject_contains
+        if conversation_id:
+            params["conversation_id"] = conversation_id
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
         if token:
             params["token"] = token
         resp = self._client.get(
@@ -200,18 +250,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())
@@ -243,17 +300,27 @@ class E2AApi:
         self,
         message_id: str,
         overrides: Optional[ApprovePendingMessageRequest] = None,
+        idempotency_key: Optional[str] = None,
     ) -> ApprovePendingMessageResponse:
         """Approve a held outbound message.
 
         Pass ``overrides`` to approve with edits (any subset of
         subject / body_text / body_html / to / cc / bcc / attachments).
         Pass ``None`` (the default) to approve the draft as-is.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Approve fires a real SES send, so supplying a stable key
+        derived from the review event makes retries safe (the server
+        replays the original response instead of double-sending).
+        When omitted the SDK mints a fresh UUIDv4 per call — that
+        gives network-layer retry safety only; the per-call default
+        does not survive an explicit retry loop.
         """
         payload = overrides.model_dump(by_alias=True, exclude_none=True) if overrides else {}
         resp = self._client.post(
             f"/api/v1/messages/{quote(message_id, safe='')}/approve",
             json=payload,
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return ApprovePendingMessageResponse.model_validate(resp.json())

{e2a-2.2.0 → e2a-2.4.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,
@@ -164,8 +164,28 @@ class AsyncE2AApi:
         status: str = "unread",
         page_size: int = 50,
         token: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> ListMessagesResponse:
+        """Async variant of :meth:`E2AApi.list_messages`. See that
+        method for the full filter / sort docs."""
         params: dict[str, str] = {"status": status, "page_size": str(page_size)}
+        if sort:
+            params["sort"] = sort
+        if from_:
+            params["from"] = from_
+        if subject_contains:
+            params["subject_contains"] = subject_contains
+        if conversation_id:
+            params["conversation_id"] = conversation_id
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
         if token:
             params["token"] = token
         resp = await self._client.get(
@@ -187,18 +207,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())
@@ -224,11 +251,15 @@ class AsyncE2AApi:
         self,
         message_id: str,
         overrides: Optional[ApprovePendingMessageRequest] = None,
+        idempotency_key: Optional[str] = None,
     ) -> ApprovePendingMessageResponse:
+        """Async variant of :meth:`E2AApi.approve_message`. ``idempotency_key``
+        closes the SES double-send window — see that method for details."""
         payload = overrides.model_dump(by_alias=True, exclude_none=True) if overrides else {}
         resp = await self._client.post(
             f"/api/v1/messages/{quote(message_id, safe='')}/approve",
             json=payload,
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return ApprovePendingMessageResponse.model_validate(resp.json())
@@ -382,10 +413,35 @@ class AsyncE2AClient:
         page_size: int = 50,
         token: Optional[str] = None,
         agent_email: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> MessageList:
-        """Fetch message summaries with ergonomic field names."""
+        """Fetch message summaries with ergonomic field names.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first). Pass
+        ``"asc"`` to drain the inbox in arrival order — FIFO polling.
+
+        Search filters (``from_``, ``subject_contains``, ``conversation_id``,
+        ``since``, ``until``) match the sync client — see
+        :meth:`E2AApi.list_messages` for the full reference.
+        """
         email = self._require_agent_email(agent_email)
-        resp = await self.api.list_messages(email, status=status, page_size=page_size, token=token)
+        resp = await self.api.list_messages(
+            email,
+            status=status,
+            page_size=page_size,
+            token=token,
+            sort=sort,
+            from_=from_,
+            subject_contains=subject_contains,
+            conversation_id=conversation_id,
+            since=since,
+            until=until,
+        )
         messages = [
             MessageSummary(
                 message_id=m.message_id or "",
@@ -394,6 +450,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 +472,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 +491,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 +509,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 +530,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 "",
@@ -542,6 +613,7 @@ class AsyncE2AClient:
         to: Optional[list[str]] = None,
         cc: Optional[list[str]] = None,
         bcc: Optional[list[str]] = None,
+        idempotency_key: Optional[str] = None,
     ):
         any_override = any(
             v is not None for v in (subject, body_text, body_html, to, cc, bcc)
@@ -558,7 +630,7 @@ class AsyncE2AClient:
             if any_override
             else None
         )
-        return await self.api.approve_message(message_id, overrides)
+        return await self.api.approve_message(message_id, overrides, idempotency_key=idempotency_key)
 
     async def reject_message(self, message_id: str, reason: str = ""):
         return await self.api.reject_message(message_id, reason)

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

@@ -185,10 +185,36 @@ class E2AClient:
         page_size: int = 50,
         token: Optional[str] = None,
         agent_email: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> MessageList:
-        """Fetch message summaries with ergonomic field names."""
+        """Fetch message summaries with ergonomic field names.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first). Pass
+        ``"asc"`` to drain the inbox in arrival order — FIFO polling.
+
+        ``from_`` / ``subject_contains`` are case-insensitive substring
+        filters (capped at 200 chars server-side). ``conversation_id``
+        exact-matches a thread. ``since`` / ``until`` are RFC3339
+        timestamps bounding ``created_at``.
+        """
         email = self._require_agent_email(agent_email)
-        resp = self.api.list_messages(email, status=status, page_size=page_size, token=token)
+        resp = self.api.list_messages(
+            email,
+            status=status,
+            page_size=page_size,
+            token=token,
+            sort=sort,
+            from_=from_,
+            subject_contains=subject_contains,
+            conversation_id=conversation_id,
+            since=since,
+            until=until,
+        )
         messages = [
             MessageSummary(
                 message_id=m.message_id or "",
@@ -197,6 +223,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 +245,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 +265,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 +283,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 +305,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 "",
@@ -352,11 +395,19 @@ class E2AClient:
         to: Optional[list[str]] = None,
         cc: Optional[list[str]] = None,
         bcc: Optional[list[str]] = None,
+        idempotency_key: Optional[str] = None,
     ):
         """Approve a held outbound message.
 
         Pass any subset of overrides to approve with edits; pass none
         to approve as-is.
+
+        ``idempotency_key`` makes retries safe across the SES double-
+        send window. Supply a stable key derived from the review event
+        (e.g. the dashboard click id or the pending ``message_id``) to
+        make retries dedupe. When omitted the SDK mints a fresh UUIDv4
+        per call — that gives network-layer retry safety only; the
+        per-call default does not survive an explicit retry loop.
         """
         any_override = any(
             v is not None for v in (subject, body_text, body_html, to, cc, bcc)
@@ -373,7 +424,7 @@ class E2AClient:
             if any_override
             else None
         )
-        return self.api.approve_message(message_id, overrides)
+        return self.api.approve_message(message_id, overrides, idempotency_key=idempotency_key)
 
     def reject_message(self, message_id: str, reason: str = ""):
         """Reject a held outbound message. The optional reason is