e2a 5.2.0__tar.gz → 5.3.0__tar.gz

{e2a-5.2.0 → e2a-5.3.0}/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## Unreleased
+## 5.3.0
+
+### Added
+- **`client.messages.delete(email, message_id, *, permanent=False)`** — move a
+  message to the trash, reversible via `client.messages.restore(...)` until the
+  trash retention window expires (30 days by default), so the soft delete needs
+  no confirmation. Pass `permanent=True` to delete forever a message that is
+  already in the trash (irreversible, account scope only; the SDK supplies the
+  `?confirm=DELETE` guard the raw API requires on that path). Available on both
+  `AsyncE2AClient` and the synchronous `E2AClient`.
+- **`client.messages.get_lifecycle(email, message_id, *, cursor=None, limit=None)`**
+  — page through a message's canonical lifecycle transitions (send, delivery,
+  bounce, review, deletion, …) as `PageMessageLifecycleTransition`. Beta.
+
+## 5.2.0
+
+The first publish to PyPI since 4.0.1: 5.0.0, 5.1.0, and 5.2.0 all reach users
+in this release, so read those three sections together when upgrading from 4.x.
 
 ### Added
 - `client.inbound.from_event(event)` returns `AsyncInboundEmail` on
@@ -41,20 +58,23 @@
   ``EventJSON`` → ``EventView``, ``Suppression`` → ``SuppressionView``,
   ``Result`` → ``AuthVerdict``, ``AttachmentMeta`` → ``AttachmentMetaView``.
 
-## 5.2.0
-
-### Breaking (pre-GA)
-- **The reserved-word wire field `from` is now uniformly exposed as `from_`
-  (PEP 8 trailing underscore) on generated models** (was the generator-mangled
-  `var_from`). Affected models: `Message`, `MessageView`, `MessageSummaryView`,
-  `ReviewView`, `EmailReceivedData`, `EmailSentData`, `EmailFailedData`
-  (generated), plus the generated `list_messages` sender filter parameter. The
+- **The reserved-word wire field `from` is exposed as `from_` (PEP 8 trailing
+  underscore) where a sender is still projected** (was the generator-mangled
+  `var_from`). This is the generated `list_messages` sender filter parameter
+  and the outbound-only `EmailSentData` / `EmailFailedData` models; the
   hand-written layer's `messages.list(from_=...)` already used `from_`, so the
-  SDK now teaches exactly one spelling; the TypeScript SDK exposes the same
+  SDK teaches exactly one spelling, and the TypeScript SDK exposes the same
   `from_`. The wire JSON is unchanged — requests and responses still carry
   `from` (pydantic alias). The webhook/WS `data` payload TypedDicts are
-  wire-true dicts and keep the literal `"from"` key (access as
-  `data["from"]`). Migrate: `message.var_from` → `message.from_`.
+  wire-true dicts and keep the literal `"from"` key (access as `data["from"]`).
+
+  An intermediate step on `main` also renamed the *inbound* sender projection
+  on `Message`, `MessageView`, `MessageSummaryView`, `ReviewView`, and
+  `EmailReceivedData` from `var_from` to `from_`. The DMARC-aligned contract
+  above replaced that projection with `header_from` before this release, so
+  `from_` never reached PyPI on those models and there is nothing to migrate
+  off — 4.x callers reading `message.var_from` go straight to
+  `message.header_from`.
 
 ## 5.1.0
 

{e2a-5.2.0 → e2a-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 5.2.0
+Version: 5.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/tokencanopy/e2a
@@ -141,6 +141,10 @@ retries + idempotency, and async auto-pagination.
 
 ## Quick Start
 
+For signed-webhook examples that fetch and reply through the ergonomic inbound
+facade, see the [minimal Python and TypeScript OpenAI examples with provider
+snippets](../../examples/agent-framework-webhooks/README.md).
+
 ### Synchronous
 
 ```python
@@ -264,7 +268,11 @@ async def webhook(request):
         # From, Reply-To, bodies, and attachment names/types are untrusted input.
         print(email.envelope_from, email.verified, email.subject, email.text)
         print("reply will target", email.reply_targets)
-        result = await email.reply({"text": "Got it"}, idempotency_key=f"reply:{event.id}")
+        agent_thread_id = await get_or_create_agent_thread(email.conversation_id)
+        result = await email.reply(
+            {"text": "Got it", "conversation_id": agent_thread_id},
+            idempotency_key=f"reply:{event.id}",
+        )
         if result.status == "pending_review":
             print("reply is awaiting approval")
     return {"ok": True}
@@ -375,18 +383,29 @@ page = client.messages.list("bot@agents.e2a.dev", limit=100).page()
 
 ### Trash and restore
 
-Soft-deleted agents and messages remain restorable for about 30 days. List the
-trash with `deleted=True`, then restore an item through the same resource. The
-sync client exposes the same methods without `await`.
+`delete()` is a soft delete: agents and messages move to the trash and stay
+restorable for about 30 days. List the trash with `deleted=True`, then restore
+an item through the same resource. The sync client exposes the same methods
+without `await`.
 
 ```python
+await client.agents.delete("bot@agents.e2a.dev")
 trashed_agents = client.agents.list(deleted=True)
 await client.agents.restore("bot@agents.e2a.dev")
 
+await client.messages.delete("bot@agents.e2a.dev", "msg_abc123")
 trashed_messages = client.messages.list("bot@agents.e2a.dev", deleted=True)
 await client.messages.restore("bot@agents.e2a.dev", "msg_abc123")
 ```
 
+A message already in the trash can be purged early and irreversibly. That path
+needs an account-scoped credential; the SDK supplies the API's `?confirm=DELETE`
+guard for you:
+
+```python
+await client.messages.delete("bot@agents.e2a.dev", "msg_abc123", permanent=True)
+```
+
 ## WebSocket (real-time delivery for local agents)
 
 ```python
@@ -427,8 +446,16 @@ e2a surfaces it on the recipient's inbound — via `In-Reply-To` for humans, or
 forge-resistant `X-E2A-Conversation-Id` header for same-platform agent-to-agent
 mail. It is not a security boundary; for sender-domain authentication require
 `message.authentication is not None and message.authentication.dmarc.status == "pass"`
-and compare the literal `message.header_from` address separately. On first contact from a human the
-conversation ID arrives `None` — assign one yourself if you want to thread.
+and compare the literal `message.header_from` address separately. On first
+contact from a human the conversation ID arrives `None`. Create the agent
+runtime's internal thread before replying, then pass its stable, non-sensitive
+thread/session ID (or an opaque stored alias) as `conversation_id`; reuse it on
+every later send or reply. If a later inbound ID matches a binding you
+previously stored, resume that internal thread. Keep replying by the original
+message ID as well — the conversation ID aligns e2a grouping with agent memory,
+while the reply endpoint sets the email headers Gmail/Outlook use. Scope
+bindings to the inbox and sender, and never use the conversation ID as
+authorization.
 
 ```python
 await client.messages.send(address, {

{e2a-5.2.0 → e2a-5.3.0}/README.md

@@ -103,6 +103,10 @@ retries + idempotency, and async auto-pagination.
 
 ## Quick Start
 
+For signed-webhook examples that fetch and reply through the ergonomic inbound
+facade, see the [minimal Python and TypeScript OpenAI examples with provider
+snippets](../../examples/agent-framework-webhooks/README.md).
+
 ### Synchronous
 
 ```python
@@ -226,7 +230,11 @@ async def webhook(request):
         # From, Reply-To, bodies, and attachment names/types are untrusted input.
         print(email.envelope_from, email.verified, email.subject, email.text)
         print("reply will target", email.reply_targets)
-        result = await email.reply({"text": "Got it"}, idempotency_key=f"reply:{event.id}")
+        agent_thread_id = await get_or_create_agent_thread(email.conversation_id)
+        result = await email.reply(
+            {"text": "Got it", "conversation_id": agent_thread_id},
+            idempotency_key=f"reply:{event.id}",
+        )
         if result.status == "pending_review":
             print("reply is awaiting approval")
     return {"ok": True}
@@ -337,18 +345,29 @@ page = client.messages.list("bot@agents.e2a.dev", limit=100).page()
 
 ### Trash and restore
 
-Soft-deleted agents and messages remain restorable for about 30 days. List the
-trash with `deleted=True`, then restore an item through the same resource. The
-sync client exposes the same methods without `await`.
+`delete()` is a soft delete: agents and messages move to the trash and stay
+restorable for about 30 days. List the trash with `deleted=True`, then restore
+an item through the same resource. The sync client exposes the same methods
+without `await`.
 
 ```python
+await client.agents.delete("bot@agents.e2a.dev")
 trashed_agents = client.agents.list(deleted=True)
 await client.agents.restore("bot@agents.e2a.dev")
 
+await client.messages.delete("bot@agents.e2a.dev", "msg_abc123")
 trashed_messages = client.messages.list("bot@agents.e2a.dev", deleted=True)
 await client.messages.restore("bot@agents.e2a.dev", "msg_abc123")
 ```
 
+A message already in the trash can be purged early and irreversibly. That path
+needs an account-scoped credential; the SDK supplies the API's `?confirm=DELETE`
+guard for you:
+
+```python
+await client.messages.delete("bot@agents.e2a.dev", "msg_abc123", permanent=True)
+```
+
 ## WebSocket (real-time delivery for local agents)
 
 ```python
@@ -389,8 +408,16 @@ e2a surfaces it on the recipient's inbound — via `In-Reply-To` for humans, or
 forge-resistant `X-E2A-Conversation-Id` header for same-platform agent-to-agent
 mail. It is not a security boundary; for sender-domain authentication require
 `message.authentication is not None and message.authentication.dmarc.status == "pass"`
-and compare the literal `message.header_from` address separately. On first contact from a human the
-conversation ID arrives `None` — assign one yourself if you want to thread.
+and compare the literal `message.header_from` address separately. On first
+contact from a human the conversation ID arrives `None`. Create the agent
+runtime's internal thread before replying, then pass its stable, non-sensitive
+thread/session ID (or an opaque stored alias) as `conversation_id`; reuse it on
+every later send or reply. If a later inbound ID matches a binding you
+previously stored, resume that internal thread. Keep replying by the original
+message ID as well — the conversation ID aligns e2a grouping with agent memory,
+while the reply endpoint sets the email headers Gmail/Outlook use. Scope
+bindings to the inbox and sender, and never use the conversation ID as
+authorization.
 
 ```python
 await client.messages.send(address, {

{e2a-5.2.0 → e2a-5.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "5.2.0"
+version = "5.3.0"
 description = "Python SDK for the e2a protocol — email-to-agent authentication"
 readme = "README.md"
 license = "Apache-2.0"
@@ -51,7 +51,7 @@ ws = ["websockets>=14"]
 
 [tool.mypy]
 python_version = "3.9"
-files = ["tests/test_e2e.py", "tests/typecheck_event_envelope.py", "tests/typecheck_inbound.py"]
+files = ["tests/test_e2e.py", "tests/typecheck_event_envelope.py", "tests/typecheck_inbound.py", "tests/typecheck_lifecycle_payloads.py"]
 follow_imports = "silent"
 show_error_codes = true
 warn_unused_ignores = true

{e2a-5.2.0 → e2a-5.3.0}/scripts/generate-oag.sh

@@ -46,9 +46,10 @@ rm -rf "$DEST"
 cp -r "$TMP/e2a/v1/generated" "$DEST"
 rm -rf "$TMP"
 
-# Strip the generator's `*_validate_enum` validators so the client tolerates
-# unknown enum values (forward-compat: a new server enum value must not crash a
-# deployed client). Matches the TypeScript SDK's passthrough behavior.
+# Strip the generator's `*_validate_enum` validators from open response
+# vocabularies so the client tolerates additive values. The post-processor
+# preserves validators for the canonical, deliberately closed message
+# lifecycle vocabulary.
 python3 "$ROOT/sdks/python/scripts/strip-enum-validators.py" "$DEST"
 
 # Normalize selected generator-known unused imports without making hand edits

{e2a-5.2.0 → e2a-5.3.0}/scripts/strip-enum-validators.py

@@ -1,14 +1,18 @@
 #!/usr/bin/env python3
-"""Strip OpenAPI-Generator's `*_validate_enum` pydantic validators from the
-generated models so the client tolerates unknown enum values.
+"""Strip OpenAPI-Generator's open-set enum validators from generated models.
 
 Why: the generator emits, for every enum-typed field, a `@field_validator` that
 raises `ValueError` when the value isn't in a hard-coded set. On a RESPONSE
 field that means the day the server adds a new enum value (a new event `type`,
 `delivery_status`, `inbound_policy`, …) every deployed client crashes while
 deserializing — turning an additive, non-breaking server change into a
-client-breaking one. The TypeScript SDK passes unknown enum values through
-untouched; this makes Python match, keeping enum fields typed as plain strings.
+client-breaking one. The TypeScript SDK passes unknown open-set enum values
+through untouched; this makes Python match, keeping those fields typed as
+plain strings.
+
+The canonical ``MessageLifecycleTransition`` vocabulary is deliberately
+closed and versioned. Its generated validators are retained so Python enforces
+the same direction, stage, outcome, and reason-code contract as the API.
 
 Run as part of generate-oag.sh (so the drift gate's regenerated output matches)
 and idempotently re-runnable on the committed tree. Removes each block of the
@@ -30,6 +34,9 @@ import re
 import sys
 
 
+CLOSED_ENUM_MODELS = {"message_lifecycle_transition.py"}
+
+
 def strip_file(path: str) -> bool:
     with open(path, "r", encoding="utf-8") as f:
         lines = f.readlines()
@@ -81,7 +88,11 @@ def main() -> int:
     root = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
         os.path.dirname(__file__), "..", "src", "e2a", "v1", "generated"
     )
-    models = glob.glob(os.path.join(root, "models", "*.py"))
+    models = [
+        path
+        for path in glob.glob(os.path.join(root, "models", "*.py"))
+        if os.path.basename(path) not in CLOSED_ENUM_MODELS
+    ]
     touched = sum(1 for p in sorted(models) if strip_file(p))
     print(f"strip-enum-validators: removed enum validators from {touched} model file(s)")
     return 0

{e2a-5.2.0 → e2a-5.3.0}/src/e2a/v1/__init__.py

@@ -102,6 +102,8 @@ __all__ = [
     "E2AClient",
     "SyncAutoPager",
     "SyncStream",
+    "MessageLifecycleTransition",
+    "PageMessageLifecycleTransition",
     # Errors
     "E2AError",
     "E2AAuthError",

e2a-5.3.0/src/e2a/v1/_event_lifecycle.py

@@ -0,0 +1,44 @@
+"""Shared lifecycle coercion for v1 stable event envelopes."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .generated.models import MessageLifecycleTransition
+
+
+_V1_STABLE_LIFECYCLE_EVENTS = {
+    "email.received",
+    "email.sent",
+    "email.failed",
+    "email.delivered",
+    "email.bounced",
+    "email.complained",
+    "domain.suppression_added",
+}
+
+
+def coerce_v1_stable_lifecycle(
+    schema_version: str,
+    event_type: str,
+    data: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Return typed lifecycle rows only for the closed v1 stable contract.
+
+    When the field is absent—or the envelope version/type is outside that
+    contract—the original data object is returned unchanged. When present, a
+    shallow copy keeps ``event.raw`` as the original wire representation.
+    """
+    if (
+        schema_version != "1"
+        or event_type not in _V1_STABLE_LIFECYCLE_EVENTS
+        or "lifecycle_transitions" not in data
+    ):
+        return data
+
+    coerced = dict(data)
+    coerced["lifecycle_transitions"] = [
+        MessageLifecycleTransition.model_validate(row)
+        for row in data["lifecycle_transitions"]
+    ]
+    return coerced

{e2a-5.2.0 → e2a-5.3.0}/src/e2a/v1/client.py

@@ -45,6 +45,7 @@ from .generated.models import (
     DeleteAgentResult,
     DeleteApiKeyResult,
     DeleteDomainResult,
+    DeleteMessageResult,
     DeleteSuppressionResult,
     DeleteTemplateResult,
     DeleteUserDataResult,
@@ -56,6 +57,7 @@ from .generated.models import (
     AccountView,
     AttachmentView,
     MessageSummaryView,
+    PageMessageLifecycleTransition,
     MessageView,
     RedeliverEventRequest,
     RedeliverView,
@@ -477,6 +479,55 @@ class MessagesResource:
     async def get(self, email: str, message_id: str) -> MessageView:
         return await self._c._read(lambda h: self._api.get_message(email, message_id, _headers=h))
 
+    async def get_lifecycle(
+        self,
+        email: str,
+        message_id: str,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> PageMessageLifecycleTransition:
+        """Beta: return the ordered observations e2a recorded for one message.
+
+        The lifecycle contract may change before it is declared stable.
+        """
+        return await self._c._read(
+            lambda h: self._api.get_message_lifecycle(
+                email,
+                message_id,
+                cursor=cursor,
+                limit=limit,
+                _headers=h,
+            )
+        )
+
+    async def delete(
+        self, email: str, message_id: str, *, permanent: bool = False
+    ) -> DeleteMessageResult:
+        """Move a message to the trash.
+
+        Reversible via ``restore()`` until the trash retention window expires
+        (30 days by default), so the default soft delete needs no confirmation.
+
+        Pass ``permanent=True`` to permanently delete a message that is ALREADY
+        in the trash ("delete forever") — irreversible, account scope only. The
+        typed .delete() call is the confirmation; the SDK supplies the
+        ?confirm=DELETE guard the raw API requires on that path (it is ignored
+        when permanent is unset).
+
+        A message held for review cannot be deleted (409 message_held) — resolve
+        it on the review queue first. Returns the deletion receipt
+        ({deleted, id}).
+        """
+        return await self._c._write_idempotent(
+            lambda h: self._api.delete_message(
+                # `permanent or None` omits the param entirely on the soft path,
+                # matching the TS SDK's wire shape (the server treats an absent
+                # and a false `permanent` identically).
+                email, message_id, permanent=permanent or None, confirm="DELETE", _headers=h
+            )
+        )
+
     async def restore(self, email: str, message_id: str) -> MessageView:
         """Restore a soft-deleted message and resume its retention clock."""
         return await self._c._write_unsafe(

{e2a-5.2.0 → e2a-5.3.0}/src/e2a/v1/generated/__init__.py

@@ -97,6 +97,7 @@ __all__ = [
     "LimitsUsageView",
     "Message",
     "MessageBodyView",
+    "MessageLifecycleTransition",
     "MessageParsedView",
     "MessageSummaryView",
     "MessageView",
@@ -107,6 +108,7 @@ __all__ = [
     "PageConversationSummaryView",
     "PageDomainView",
     "PageEventView",
+    "PageMessageLifecycleTransition",
     "PageMessageSummaryView",
     "PageReviewView",
     "PageStarterTemplateView",
@@ -260,6 +262,7 @@ from e2a.v1.generated.models.limits_caps_view import LimitsCapsView as LimitsCap
 from e2a.v1.generated.models.limits_usage_view import LimitsUsageView as LimitsUsageView
 from e2a.v1.generated.models.message import Message as Message
 from e2a.v1.generated.models.message_body_view import MessageBodyView as MessageBodyView
+from e2a.v1.generated.models.message_lifecycle_transition import MessageLifecycleTransition as MessageLifecycleTransition
 from e2a.v1.generated.models.message_parsed_view import MessageParsedView as MessageParsedView
 from e2a.v1.generated.models.message_summary_view import MessageSummaryView as MessageSummaryView
 from e2a.v1.generated.models.message_view import MessageView as MessageView
@@ -270,6 +273,7 @@ from e2a.v1.generated.models.page_agent_view import PageAgentView as PageAgentVi
 from e2a.v1.generated.models.page_conversation_summary_view import PageConversationSummaryView as PageConversationSummaryView
 from e2a.v1.generated.models.page_domain_view import PageDomainView as PageDomainView
 from e2a.v1.generated.models.page_event_view import PageEventView as PageEventView
+from e2a.v1.generated.models.page_message_lifecycle_transition import PageMessageLifecycleTransition as PageMessageLifecycleTransition
 from e2a.v1.generated.models.page_message_summary_view import PageMessageSummaryView as PageMessageSummaryView
 from e2a.v1.generated.models.page_review_view import PageReviewView as PageReviewView
 from e2a.v1.generated.models.page_starter_template_view import PageStarterTemplateView as PageStarterTemplateView