e2a 2.0.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.0.0
+Version: 2.2.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
@@ -48,6 +48,17 @@ For WebSocket real-time delivery:
 pip install e2a[ws]
 ```
 
+## Upgrading from 1.x to 2.0
+
+Webhook-parsed emails now refuse to expose claim fields (`sender`, `subject`, `text_body`, …) until the HMAC signature is verified — `email.sender` raises `UnverifiedEmailError` instead of silently returning attacker-controllable data. The one-line fix is to switch `client.parse(body)` → `client.parse_webhook(body)`:
+
+```diff
+- email = client.parse(await request.body())
++ email = client.parse_webhook(await request.body())
+```
+
+`parse_webhook` reads the secret from `E2A_WEBHOOK_SECRET`; set it before upgrading. If you must inspect the payload before verifying, use `email.unverified_payload`. REST-fetched emails (`client.get_message`) are unaffected — they're pre-verified via the bearer token. Full background in the [PR](https://github.com/Mnexa-AI/e2a/pull/57).
+
 ## Import paths
 
 The stable, pinned API surface lives under `e2a.v1`:
@@ -72,15 +83,22 @@ client = E2AClient()
 
 Mount the webhook in your web framework:
 
+Webhook payloads are HMAC-signed. The SDK gates field access behind verification — accessing `email.sender`, `email.subject`, etc. on an unverified payload raises `UnverifiedEmailError`. Use `client.parse_webhook(...)` to parse + verify in one call:
+
 **FastAPI:**
 ```python
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, HTTPException
 
 app = FastAPI()
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    try:
+        email = client.parse_webhook(await request.body())  # reads E2A_WEBHOOK_SECRET
+    except PermissionError:
+        raise HTTPException(401, "bad signature")
+    # ValueError is raised if no secret is configured — let it 500 so a misconfig
+    # surfaces loudly, or catch it here to return a clearer message.
     print(f"From: {email.sender}, Subject: {email.subject}")
     email.reply("Thanks for reaching out!")
     return {"ok": True}
@@ -88,17 +106,22 @@ async def webhook(request: Request):
 
 **Flask:**
 ```python
-from flask import Flask, request
+from flask import Flask, request, abort
 
 app = Flask(__name__)
 
 @app.post("/webhook")
 def webhook():
-    email = client.parse(request.get_data())
+    try:
+        email = client.parse_webhook(request.get_data())
+    except PermissionError:
+        abort(401)
     email.reply("Thanks for reaching out!")
     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_...")`.
+
 ## Raw vs high-level API
 
 The SDK has two layers:
@@ -132,7 +155,7 @@ whether the other side is a human replying from Gmail or another e2a agent.
 ```python
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = client.parse_webhook(await request.body())
 
     if email.conversation_id:
         # Follow-up — route to the existing conversation
@@ -220,7 +243,7 @@ Inbound email attachments are automatically parsed and available on
 `email.attachments`:
 
 ```python
-email = client.parse(body)
+email = client.parse_webhook(body)
 for att in email.attachments:
     print(f"{att.filename} ({att.content_type}, {att.size} bytes)")
     save_file(att.filename, att.data)
@@ -273,7 +296,7 @@ client = AsyncE2AClient()  # reads E2A_API_KEY from env
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = await client.parse_webhook(await request.body())
     await email.reply("Thanks!", conversation_id="conv_123")
     return {"ok": True}
 ```
@@ -393,9 +416,13 @@ 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.
+
 **Methods:**
 
+- `email.verify_signature(secret=None)` → `bool` — verifies the HMAC; falls back to `E2A_WEBHOOK_SECRET`. Sets the verified flag on success so claim fields become accessible.
 - `email.reply(body, html_body=None, conversation_id=None, attachments=None)` → `SendResult`
+- `email.unverified_payload` — escape hatch for inspection (debugging, logging) without verifying. Treat as untrusted.
 
 ## API Reference
 
@@ -403,8 +430,9 @@ print(result.status, result.message_id)
 
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`
-- `client.get_message(message_id)` → `InboundEmail`
+- `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` — *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`
 - `client.send(to, subject, body, ...)` → `SendResult`
@@ -422,11 +450,13 @@ Same as `E2AClient` — all I/O methods are `async`. `parse()` is sync (no I/O n
 - `InboundEmail` / `AsyncInboundEmail` — parsed email with `.reply()`
 - `Attachment` — `filename`, `content_type`, `data` (bytes), `size`
 - `SendResult` — `status`, `message_id`, `method`
-- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`, `message_id`, `body_hash`
 
 ### Exceptions
 
 - `E2AApiError` — API error (has `status_code` and `message`)
+- `UnverifiedEmailError` — raised on `InboundEmail` claim-field access before `verify_signature()` has succeeded
+- `PermissionError` — raised by `parse_webhook` on bad signature
 
 ## License
 

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

@@ -14,6 +14,17 @@ For WebSocket real-time delivery:
 pip install e2a[ws]
 ```
 
+## Upgrading from 1.x to 2.0
+
+Webhook-parsed emails now refuse to expose claim fields (`sender`, `subject`, `text_body`, …) until the HMAC signature is verified — `email.sender` raises `UnverifiedEmailError` instead of silently returning attacker-controllable data. The one-line fix is to switch `client.parse(body)` → `client.parse_webhook(body)`:
+
+```diff
+- email = client.parse(await request.body())
++ email = client.parse_webhook(await request.body())
+```
+
+`parse_webhook` reads the secret from `E2A_WEBHOOK_SECRET`; set it before upgrading. If you must inspect the payload before verifying, use `email.unverified_payload`. REST-fetched emails (`client.get_message`) are unaffected — they're pre-verified via the bearer token. Full background in the [PR](https://github.com/Mnexa-AI/e2a/pull/57).
+
 ## Import paths
 
 The stable, pinned API surface lives under `e2a.v1`:
@@ -38,15 +49,22 @@ client = E2AClient()
 
 Mount the webhook in your web framework:
 
+Webhook payloads are HMAC-signed. The SDK gates field access behind verification — accessing `email.sender`, `email.subject`, etc. on an unverified payload raises `UnverifiedEmailError`. Use `client.parse_webhook(...)` to parse + verify in one call:
+
 **FastAPI:**
 ```python
-from fastapi import FastAPI, Request
+from fastapi import FastAPI, Request, HTTPException
 
 app = FastAPI()
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    try:
+        email = client.parse_webhook(await request.body())  # reads E2A_WEBHOOK_SECRET
+    except PermissionError:
+        raise HTTPException(401, "bad signature")
+    # ValueError is raised if no secret is configured — let it 500 so a misconfig
+    # surfaces loudly, or catch it here to return a clearer message.
     print(f"From: {email.sender}, Subject: {email.subject}")
     email.reply("Thanks for reaching out!")
     return {"ok": True}
@@ -54,17 +72,22 @@ async def webhook(request: Request):
 
 **Flask:**
 ```python
-from flask import Flask, request
+from flask import Flask, request, abort
 
 app = Flask(__name__)
 
 @app.post("/webhook")
 def webhook():
-    email = client.parse(request.get_data())
+    try:
+        email = client.parse_webhook(request.get_data())
+    except PermissionError:
+        abort(401)
     email.reply("Thanks for reaching out!")
     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_...")`.
+
 ## Raw vs high-level API
 
 The SDK has two layers:
@@ -98,7 +121,7 @@ whether the other side is a human replying from Gmail or another e2a agent.
 ```python
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = client.parse_webhook(await request.body())
 
     if email.conversation_id:
         # Follow-up — route to the existing conversation
@@ -186,7 +209,7 @@ Inbound email attachments are automatically parsed and available on
 `email.attachments`:
 
 ```python
-email = client.parse(body)
+email = client.parse_webhook(body)
 for att in email.attachments:
     print(f"{att.filename} ({att.content_type}, {att.size} bytes)")
     save_file(att.filename, att.data)
@@ -239,7 +262,7 @@ client = AsyncE2AClient()  # reads E2A_API_KEY from env
 
 @app.post("/webhook")
 async def webhook(request: Request):
-    email = client.parse(await request.body())
+    email = await client.parse_webhook(await request.body())
     await email.reply("Thanks!", conversation_id="conv_123")
     return {"ok": True}
 ```
@@ -359,9 +382,13 @@ 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.
+
 **Methods:**
 
+- `email.verify_signature(secret=None)` → `bool` — verifies the HMAC; falls back to `E2A_WEBHOOK_SECRET`. Sets the verified flag on success so claim fields become accessible.
 - `email.reply(body, html_body=None, conversation_id=None, attachments=None)` → `SendResult`
+- `email.unverified_payload` — escape hatch for inspection (debugging, logging) without verifying. Treat as untrusted.
 
 ## API Reference
 
@@ -369,8 +396,9 @@ print(result.status, result.message_id)
 
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`
-- `client.get_message(message_id)` → `InboundEmail`
+- `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` — *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`
 - `client.send(to, subject, body, ...)` → `SendResult`
@@ -388,11 +416,13 @@ Same as `E2AClient` — all I/O methods are `async`. `parse()` is sync (no I/O n
 - `InboundEmail` / `AsyncInboundEmail` — parsed email with `.reply()`
 - `Attachment` — `filename`, `content_type`, `data` (bytes), `size`
 - `SendResult` — `status`, `message_id`, `method`
-- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `delegation`, `signature`, `timestamp`, `message_id`, `body_hash`
 
 ### Exceptions
 
 - `E2AApiError` — API error (has `status_code` and `message`)
+- `UnverifiedEmailError` — raised on `InboundEmail` claim-field access before `verify_signature()` has succeeded
+- `PermissionError` — raised by `parse_webhook` on bad signature
 
 ## License
 

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

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

{e2a-2.0.0 → e2a-2.2.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
 
@@ -306,13 +307,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 +355,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

{e2a-2.0.0 → e2a-2.2.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):
@@ -123,10 +149,10 @@ class E2AClient:
         works. Raises :class:`PermissionError` on signature failure
         (so a webhook handler can let the exception bubble to a 401).
 
-        ``secret`` defaults to the ``E2A_HMAC_SECRET`` environment
-        variable.
+        ``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

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

@@ -131,6 +131,36 @@ def _verify_auth_headers(
     return hmac.compare_digest(h.signature, expected)
 
 
+_warned_legacy_env = False
+
+
+def _resolve_webhook_secret() -> str:
+    """Read the webhook signing secret from env, preferring the new name.
+
+    Order: ``E2A_WEBHOOK_SECRET`` (canonical) → ``E2A_HMAC_SECRET`` (legacy
+    alias, kept for backward compatibility with SDK 2.0). Emits a one-time
+    DeprecationWarning when only the legacy name is set so users notice
+    before the alias is removed in a future major release.
+    """
+    val = os.environ.get("E2A_WEBHOOK_SECRET", "")
+    if val:
+        return val
+    legacy = os.environ.get("E2A_HMAC_SECRET", "")
+    if legacy:
+        global _warned_legacy_env
+        if not _warned_legacy_env:
+            import warnings
+            warnings.warn(
+                "E2A_HMAC_SECRET is deprecated; rename it to E2A_WEBHOOK_SECRET. "
+                "The legacy name will be removed in a future major release.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            _warned_legacy_env = True
+        return legacy
+    return ""
+
+
 @dataclass
 class Attachment:
     """An email attachment."""
@@ -312,13 +342,16 @@ class InboundEmail:
         On success, transitions this instance to the "verified" state
         so subsequent property reads (sender, subject, body, …) work.
 
-        ``secret`` defaults to the ``E2A_HMAC_SECRET`` environment
-        variable when omitted, so the standard webhook-handler pattern
-        is just::
+        ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
+        variable when omitted (with ``E2A_HMAC_SECRET`` accepted as a
+        deprecated alias).
 
-            email = client.parse(body)
-            if not email.verify_signature():
-                return 401
+        Most webhook handlers should use :meth:`E2AClient.parse_webhook`
+        instead — it calls ``verify_signature`` internally and raises
+        ``PermissionError`` on failure, so the handler reads as one
+        concise call. Use ``verify_signature`` directly only when you
+        need to inspect ``unverified_payload`` first or have some other
+        reason to keep the unverified object around.
 
         Checks (in order):
 
@@ -336,11 +369,11 @@ class InboundEmail:
         a verify attempt that always fails.
         """
         if secret is None:
-            secret = os.environ.get("E2A_HMAC_SECRET", "")
+            secret = _resolve_webhook_secret()
         if not secret:
             raise ValueError(
                 "verify_signature requires a secret. Pass it explicitly "
-                "or set E2A_HMAC_SECRET in the environment."
+                "or set E2A_WEBHOOK_SECRET in the environment."
             )
         ok = _verify_auth_headers(self._auth, self._raw_message, secret)
         if ok:
@@ -672,11 +705,11 @@ class AsyncInboundEmail:
     def verify_signature(self, secret: Optional[str] = None) -> bool:
         """See :meth:`InboundEmail.verify_signature` — identical contract."""
         if secret is None:
-            secret = os.environ.get("E2A_HMAC_SECRET", "")
+            secret = _resolve_webhook_secret()
         if not secret:
             raise ValueError(
                 "verify_signature requires a secret. Pass it explicitly "
-                "or set E2A_HMAC_SECRET in the environment."
+                "or set E2A_WEBHOOK_SECRET in the environment."
             )
         ok = _verify_auth_headers(self._auth, self._raw_message, secret)
         if ok:

{e2a-2.0.0 → e2a-2.2.0}/tests/test_v1_async_client.py

@@ -121,6 +121,36 @@ async def test_parse_unsupported_type():
             client.parse(12345)
 
 
+@pytest.mark.anyio
+async def test_parse_emits_deprecation_warning():
+    """Mirror of the sync test — async client's `parse` must also emit
+    the deprecation warning so async webhook handlers see the same
+    migration signal."""
+    webhook = _make_message_detail_json()
+    async with AsyncE2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with pytest.warns(DeprecationWarning, match="parse_webhook"):
+            client.parse(webhook)
+
+
+@pytest.mark.anyio
+async def test_parse_webhook_does_not_emit_deprecation_warning(monkeypatch):
+    """Same regression guard as the sync test — `parse_webhook` must not
+    surface the deprecation warning meant for direct `parse` callers."""
+    import warnings
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "secret-xyz")
+    webhook = _make_message_detail_json()
+    async with AsyncE2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            try:
+                client.parse_webhook(webhook)
+            except DeprecationWarning:
+                pytest.fail("parse_webhook should not emit DeprecationWarning")
+            except PermissionError:
+                pass
+
+
 # ── get_message() ────────────────────────────────────────────────
 
 

{e2a-2.0.0 → e2a-2.2.0}/tests/test_v1_client.py

@@ -116,6 +116,40 @@ def test_parse_unsupported_type():
             client.parse(12345)
 
 
+def test_parse_emits_deprecation_warning():
+    """Calling the legacy `parse` method on the sync client emits a
+    DeprecationWarning that points users at parse_webhook. Pin the
+    deprecation contract so it isn't silently dropped before 3.0."""
+    webhook = _make_message_detail_json()
+    with E2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with pytest.warns(DeprecationWarning, match="parse_webhook"):
+            client.parse(webhook)
+
+
+def test_parse_webhook_does_not_emit_deprecation_warning(monkeypatch):
+    """The recommended path must not emit the deprecation warning even
+    though it shares the underlying parse logic. Regression: an early
+    refactor had parse_webhook delegate to parse(), which made every
+    correct caller see the deprecation message."""
+    import warnings
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "secret-xyz")
+    webhook = _make_message_detail_json()
+    with E2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            try:
+                client.parse_webhook(webhook)
+            except DeprecationWarning:
+                pytest.fail("parse_webhook should not emit DeprecationWarning")
+            except PermissionError:
+                # Expected — fixture body has no real signature, so
+                # verify_signature returns False and parse_webhook raises.
+                # The point of this test is the absence of DeprecationWarning,
+                # which we'd have hit before the PermissionError if present.
+                pass
+
+
 # ── get_message() ────────────────────────────────────────────────
 
 

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

@@ -452,18 +452,20 @@ def test_unverified_email_allows_verify_inputs():
 
 def test_verify_signature_with_no_secret_and_no_env_raises(monkeypatch):
     """No secret + no env → ValueError (better than silent False)."""
+    monkeypatch.delenv("E2A_WEBHOOK_SECRET", raising=False)
     monkeypatch.delenv("E2A_HMAC_SECRET", raising=False)
     raw = _make_raw_email()
     data = _make_webhook_data(raw)
     email = build_inbound_email(data, _mock_client())
 
-    with pytest.raises(ValueError, match="E2A_HMAC_SECRET"):
+    with pytest.raises(ValueError, match="E2A_WEBHOOK_SECRET"):
         email.verify_signature()
 
 
 def test_verify_signature_reads_env_when_no_arg(monkeypatch):
-    """Default secret comes from E2A_HMAC_SECRET when not passed."""
-    monkeypatch.setenv("E2A_HMAC_SECRET", "wrong-secret-but-not-empty")
+    """Default secret comes from E2A_WEBHOOK_SECRET when not passed."""
+    monkeypatch.delenv("E2A_HMAC_SECRET", raising=False)
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "wrong-secret-but-not-empty")
     raw = _make_raw_email()
     data = _make_webhook_data(raw)
     email = build_inbound_email(data, _mock_client())
@@ -474,6 +476,46 @@ def test_verify_signature_reads_env_when_no_arg(monkeypatch):
     assert email.verify_signature() is False
 
 
+def test_verify_signature_falls_back_to_legacy_env(monkeypatch, recwarn):
+    """E2A_HMAC_SECRET still works for SDK 2.0 users, with a deprecation warning."""
+    # Reset the module-level "warned once" flag so this test sees the warning
+    # regardless of test ordering.
+    from e2a.v1 import handler as _handler
+    _handler._warned_legacy_env = False
+
+    monkeypatch.delenv("E2A_WEBHOOK_SECRET", raising=False)
+    monkeypatch.setenv("E2A_HMAC_SECRET", "wrong-secret-but-not-empty")
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    email = build_inbound_email(data, _mock_client())
+
+    assert email.verify_signature() is False  # called the verify path
+    deprecations = [w for w in recwarn.list if issubclass(w.category, DeprecationWarning)]
+    assert any("E2A_HMAC_SECRET" in str(w.message) for w in deprecations), (
+        "expected DeprecationWarning mentioning E2A_HMAC_SECRET"
+    )
+
+
+def test_verify_signature_prefers_canonical_env_over_legacy(monkeypatch):
+    """When both names are set, E2A_WEBHOOK_SECRET wins (no warning)."""
+    from e2a.v1 import handler as _handler
+    _handler._warned_legacy_env = False
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "canonical-wrong")
+    monkeypatch.setenv("E2A_HMAC_SECRET", "legacy-wrong")
+    raw = _make_raw_email()
+    data = _make_webhook_data(raw)
+    email = build_inbound_email(data, _mock_client())
+
+    import warnings
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        assert email.verify_signature() is False
+        assert not any(issubclass(w.category, DeprecationWarning) for w in caught), (
+            "should not warn when canonical env var is set"
+        )
+
+
 def test_verify_signature_unlocks_field_access_on_success():
     """A successful verify_signature() flips _verified and unlocks fields."""
     raw = _make_raw_email()