e2a 0.1.0__tar.gz

e2a-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+bin/
+/e2a
+*.exe
+.env
+.DS_Store
+config.local.yaml
+client_secret_*.json
+
+# Web app
+web/node_modules/
+web/.next/
+web/out/
+web/.env.local
+
+# Python SDK
+sdks/python/.venv/
+sdks/python/__pycache__/
+sdks/python/src/*.egg-info/
+sdks/python/.pytest_cache/
+*.pyc

e2a-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: e2a
+Version: 0.1.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
+Project-URL: Documentation, https://e2a.dev
+Author-email: Mnexa AI <josh@mnexa.ai>
+License-Expression: MIT
+Keywords: agent,authentication,e2a,email,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-httpx; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# e2a Python SDK
+
+Python SDK for the [e2a protocol](https://e2a.dev) — email-to-agent authentication.
+
+## Install
+
+```bash
+pip install e2a
+```
+
+## Quick start
+
+### Verify and parse incoming webhooks
+
+```python
+from e2a import E2AClient, parse_payload
+
+client = E2AClient(
+    api_key="e2a_your_api_key",
+    signing_key="e2a_your_signing_key",
+)
+
+# In your webhook handler (Flask, FastAPI, etc.)
+def handle_webhook(request):
+    body = request.get_data()
+    signature = request.headers["X-E2A-Webhook-Signature"]
+
+    if not client.verify_webhook(body, signature):
+        return "invalid signature", 401
+
+    payload = parse_payload(request.json, dict(request.headers))
+
+    print(f"From: {payload.sender}")
+    print(f"To: {payload.recipient}")
+    print(f"Verified: {payload.auth.verified}")
+    print(f"Message ID: {payload.message_id}")
+```
+
+### Reply to an email
+
+```python
+# Use the message_id from the webhook payload
+result = client.reply(
+    message_id=payload.message_id,
+    body="Thanks for your email!",
+    html_body="<p>Thanks for your email!</p>",  # optional
+)
+print(f"Sent via {result.method}, ID: {result.message_id}")
+```
+
+### Send a new email
+
+```python
+result = client.send(
+    to="alice@example.com",
+    subject="Hello from my agent",
+    body="This is a message from an AI agent.",
+)
+```
+
+## Conversation threading
+
+e2a supports an opaque `conversation_id` that lets your agent track multi-turn
+email threads. This is useful when your agent system has its own concept of
+conversations and needs to route follow-up emails to the right one.
+
+**How it works:**
+
+1. When your agent replies or sends an email, pass a `conversation_id`.
+   e2a stores a mapping from the outgoing email's Message-ID to your conversation ID.
+
+2. When a human replies to that email, e2a matches the `In-Reply-To` header
+   against stored Message-IDs and includes `conversation_id` in the webhook payload.
+
+3. For first-contact emails (no prior thread), `conversation_id` is `None`.
+
+```python
+@app.post("/webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    signature = request.headers.get("X-E2A-Webhook-Signature", "")
+
+    if not e2a.verify_webhook(body, signature):
+        raise HTTPException(401, "invalid signature")
+
+    payload = parse_payload(await request.json(), dict(request.headers))
+
+    if payload.conversation_id:
+        # This is a follow-up — route to the existing conversation
+        conversation = get_conversation(payload.conversation_id)
+    else:
+        # First contact — create a new conversation
+        conversation = create_conversation(sender=payload.sender)
+
+    response = conversation.generate_reply(payload)
+
+    # Tag the reply with your conversation ID so future emails are linked
+    e2a.reply(
+        payload.message_id,
+        body=response.text,
+        html_body=response.html,
+        conversation_id=conversation.id,
+    )
+
+    return {"ok": True}
+```
+
+The same works for `client.send()` — pass `conversation_id` when initiating an
+outbound email, and any reply to it will arrive with that ID in the webhook.
+
+```python
+result = client.send(
+    to="alice@example.com",
+    subject="Following up",
+    body="Hi Alice, just checking in.",
+    conversation_id="conv_abc123",
+)
+# When Alice replies, the webhook will include conversation_id="conv_abc123"
+```
+
+### FastAPI example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from e2a import E2AClient, parse_payload
+
+app = FastAPI()
+e2a = E2AClient(api_key="e2a_...", signing_key="e2a_...")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    signature = request.headers.get("X-E2A-Webhook-Signature", "")
+
+    if not e2a.verify_webhook(body, signature):
+        raise HTTPException(401, "invalid signature")
+
+    data = await request.json()
+    payload = parse_payload(data, dict(request.headers))
+
+    # Process the email...
+    response = process_email(payload)
+
+    # Reply
+    if payload.message_id:
+        e2a.reply(payload.message_id, body=response)
+
+    return {"ok": True}
+```
+
+## API Reference
+
+### `E2AClient(api_key, signing_key, base_url="https://e2a.dev")`
+
+- `client.reply(message_id, body, html_body=None, conversation_id=None)` → `SendResult`
+- `client.send(to, subject, body, content_type=None, conversation_id=None)` → `SendResult`
+- `client.verify_webhook(body, signature)` → `bool`
+
+### `verify_signature(body, signature, signing_key)` → `bool`
+
+### `parse_payload(data, headers)` → `WebhookPayload`
+
+### Models
+
+- `WebhookPayload` — `message_id`, `conversation_id`, `sender`, `recipient`, `raw_message`, `auth`, `received_at`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `agent_id`, `human_id`
+- `SendResult` — `status`, `message_id`, `method`
+- `E2AError` — raised on API errors, has `status_code` and `message`

e2a-0.1.0/README.md

@@ -0,0 +1,168 @@
+# e2a Python SDK
+
+Python SDK for the [e2a protocol](https://e2a.dev) — email-to-agent authentication.
+
+## Install
+
+```bash
+pip install e2a
+```
+
+## Quick start
+
+### Verify and parse incoming webhooks
+
+```python
+from e2a import E2AClient, parse_payload
+
+client = E2AClient(
+    api_key="e2a_your_api_key",
+    signing_key="e2a_your_signing_key",
+)
+
+# In your webhook handler (Flask, FastAPI, etc.)
+def handle_webhook(request):
+    body = request.get_data()
+    signature = request.headers["X-E2A-Webhook-Signature"]
+
+    if not client.verify_webhook(body, signature):
+        return "invalid signature", 401
+
+    payload = parse_payload(request.json, dict(request.headers))
+
+    print(f"From: {payload.sender}")
+    print(f"To: {payload.recipient}")
+    print(f"Verified: {payload.auth.verified}")
+    print(f"Message ID: {payload.message_id}")
+```
+
+### Reply to an email
+
+```python
+# Use the message_id from the webhook payload
+result = client.reply(
+    message_id=payload.message_id,
+    body="Thanks for your email!",
+    html_body="<p>Thanks for your email!</p>",  # optional
+)
+print(f"Sent via {result.method}, ID: {result.message_id}")
+```
+
+### Send a new email
+
+```python
+result = client.send(
+    to="alice@example.com",
+    subject="Hello from my agent",
+    body="This is a message from an AI agent.",
+)
+```
+
+## Conversation threading
+
+e2a supports an opaque `conversation_id` that lets your agent track multi-turn
+email threads. This is useful when your agent system has its own concept of
+conversations and needs to route follow-up emails to the right one.
+
+**How it works:**
+
+1. When your agent replies or sends an email, pass a `conversation_id`.
+   e2a stores a mapping from the outgoing email's Message-ID to your conversation ID.
+
+2. When a human replies to that email, e2a matches the `In-Reply-To` header
+   against stored Message-IDs and includes `conversation_id` in the webhook payload.
+
+3. For first-contact emails (no prior thread), `conversation_id` is `None`.
+
+```python
+@app.post("/webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    signature = request.headers.get("X-E2A-Webhook-Signature", "")
+
+    if not e2a.verify_webhook(body, signature):
+        raise HTTPException(401, "invalid signature")
+
+    payload = parse_payload(await request.json(), dict(request.headers))
+
+    if payload.conversation_id:
+        # This is a follow-up — route to the existing conversation
+        conversation = get_conversation(payload.conversation_id)
+    else:
+        # First contact — create a new conversation
+        conversation = create_conversation(sender=payload.sender)
+
+    response = conversation.generate_reply(payload)
+
+    # Tag the reply with your conversation ID so future emails are linked
+    e2a.reply(
+        payload.message_id,
+        body=response.text,
+        html_body=response.html,
+        conversation_id=conversation.id,
+    )
+
+    return {"ok": True}
+```
+
+The same works for `client.send()` — pass `conversation_id` when initiating an
+outbound email, and any reply to it will arrive with that ID in the webhook.
+
+```python
+result = client.send(
+    to="alice@example.com",
+    subject="Following up",
+    body="Hi Alice, just checking in.",
+    conversation_id="conv_abc123",
+)
+# When Alice replies, the webhook will include conversation_id="conv_abc123"
+```
+
+### FastAPI example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from e2a import E2AClient, parse_payload
+
+app = FastAPI()
+e2a = E2AClient(api_key="e2a_...", signing_key="e2a_...")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    signature = request.headers.get("X-E2A-Webhook-Signature", "")
+
+    if not e2a.verify_webhook(body, signature):
+        raise HTTPException(401, "invalid signature")
+
+    data = await request.json()
+    payload = parse_payload(data, dict(request.headers))
+
+    # Process the email...
+    response = process_email(payload)
+
+    # Reply
+    if payload.message_id:
+        e2a.reply(payload.message_id, body=response)
+
+    return {"ok": True}
+```
+
+## API Reference
+
+### `E2AClient(api_key, signing_key, base_url="https://e2a.dev")`
+
+- `client.reply(message_id, body, html_body=None, conversation_id=None)` → `SendResult`
+- `client.send(to, subject, body, content_type=None, conversation_id=None)` → `SendResult`
+- `client.verify_webhook(body, signature)` → `bool`
+
+### `verify_signature(body, signature, signing_key)` → `bool`
+
+### `parse_payload(data, headers)` → `WebhookPayload`
+
+### Models
+
+- `WebhookPayload` — `message_id`, `conversation_id`, `sender`, `recipient`, `raw_message`, `auth`, `received_at`
+- `AuthHeaders` — `verified`, `sender`, `entity_type`, `domain_check`, `agent_id`, `human_id`
+- `SendResult` — `status`, `message_id`, `method`
+- `E2AError` — raised on API errors, has `status_code` and `message`

e2a-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "e2a"
+version = "0.1.0"
+description = "Python SDK for the e2a protocol — email-to-agent authentication"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Mnexa AI", email = "josh@mnexa.ai" }]
+keywords = ["email", "agent", "authentication", "e2a", "webhook"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://e2a.dev"
+Repository = "https://github.com/Mnexa-AI/e2a"
+Documentation = "https://e2a.dev"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-httpx", "build", "twine"]

e2a-0.1.0/src/e2a/__init__.py

@@ -0,0 +1,12 @@
+from e2a.client import E2AClient
+from e2a.models import WebhookPayload, AuthHeaders, SendResult
+from e2a.webhook import verify_signature, parse_payload
+
+__all__ = [
+    "E2AClient",
+    "WebhookPayload",
+    "AuthHeaders",
+    "SendResult",
+    "verify_signature",
+    "parse_payload",
+]

e2a-0.1.0/src/e2a/client.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from e2a.models import SendResult
+
+
+class E2AClient:
+    """Client for the e2a API.
+
+    Args:
+        api_key: Your agent's API key (starts with ``e2a_``).
+        signing_key: Your agent's signing key for verifying webhooks.
+        base_url: e2a API base URL. Defaults to ``https://e2a.dev``.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        signing_key: str,
+        base_url: str = "https://e2a.dev",
+        timeout: float = 30,
+    ) -> None:
+        self.api_key = api_key
+        self.signing_key = signing_key
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def reply(
+        self,
+        message_id: str,
+        body: str,
+        html_body: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+    ) -> SendResult:
+        """Reply to an inbound email.
+
+        Args:
+            message_id: The ``message_id`` from the webhook payload.
+            body: Plain-text reply body.
+            html_body: Optional HTML body for rich replies.
+            conversation_id: Optional opaque ID for your conversation/thread.
+                When provided, e2a stores a mapping so that follow-up emails
+                in the same thread will include this ID in the webhook payload.
+
+        Returns:
+            A SendResult with status, message_id, and delivery method.
+
+        Raises:
+            E2AError: If the API returns an error.
+        """
+        payload: dict = {"body": body}
+        if html_body:
+            payload["html_body"] = html_body
+        if conversation_id:
+            payload["conversation_id"] = conversation_id
+
+        resp = self._client.post(f"/api/messages/{message_id}/reply", json=payload)
+        _check_response(resp)
+        data = resp.json()
+        return SendResult(
+            status=data["status"],
+            message_id=data["message_id"],
+            method=data["method"],
+        )
+
+    def send(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        content_type: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+    ) -> SendResult:
+        """Send a new email.
+
+        Args:
+            to: Recipient email address.
+            subject: Email subject.
+            body: Email body.
+            content_type: MIME content type (defaults to text/plain).
+            conversation_id: Optional opaque ID for your conversation/thread.
+                When provided, e2a stores a mapping so that replies to this
+                email will include this ID in the webhook payload.
+
+        Returns:
+            A SendResult with status, message_id, and delivery method.
+
+        Raises:
+            E2AError: If the API returns an error.
+        """
+        payload: dict = {"to": to, "subject": subject, "body": body}
+        if content_type:
+            payload["content_type"] = content_type
+        if conversation_id:
+            payload["conversation_id"] = conversation_id
+
+        resp = self._client.post("/api/send", json=payload)
+        _check_response(resp)
+        data = resp.json()
+        return SendResult(
+            status=data["status"],
+            message_id=data["message_id"],
+            method=data["method"],
+        )
+
+    def verify_webhook(self, body: bytes, signature: str) -> bool:
+        """Verify a webhook signature using this client's signing key.
+
+        Args:
+            body: Raw request body bytes.
+            signature: Value of the X-E2A-Webhook-Signature header.
+
+        Returns:
+            True if the signature is valid.
+        """
+        from e2a.webhook import verify_signature
+
+        return verify_signature(body, signature, self.signing_key)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> E2AClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class E2AError(Exception):
+    """Raised when the e2a API returns an error."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"e2a API error ({status_code}): {message}")
+
+
+def _check_response(resp: httpx.Response) -> None:
+    if resp.status_code >= 400:
+        try:
+            message = resp.text.strip()
+        except Exception:
+            message = f"HTTP {resp.status_code}"
+        raise E2AError(resp.status_code, message)

e2a-0.1.0/src/e2a/models.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class AuthHeaders:
+    """Parsed e2a authentication headers from a webhook request."""
+
+    verified: bool
+    sender: str
+    entity_type: str  # "human" or "agent"
+    domain_check: str
+    agent_id: str
+    human_id: str
+
+    @classmethod
+    def from_headers(cls, headers: dict[str, str]) -> AuthHeaders:
+        return cls(
+            verified=headers.get("X-E2A-Auth-Verified", "").lower() == "true",
+            sender=headers.get("X-E2A-Auth-Sender", ""),
+            entity_type=headers.get("X-E2A-Auth-Entity-Type", ""),
+            domain_check=headers.get("X-E2A-Auth-Domain-Check", ""),
+            agent_id=headers.get("X-E2A-Auth-Agent-Id", ""),
+            human_id=headers.get("X-E2A-Auth-Human-Id", ""),
+        )
+
+
+@dataclass
+class WebhookPayload:
+    """Parsed webhook payload from e2a.
+
+    Attributes:
+        message_id: Unique e2a message identifier (use this to reply).
+        sender: Sender email address.
+        recipient: Recipient email address (your agent's address).
+        raw_message: Raw RFC 2822 email bytes.
+        auth: Parsed authentication headers (verified status, sender identity, etc.).
+        received_at: When e2a received the email.
+        conversation_id: Your opaque conversation/thread ID, if a prior reply in this
+            thread included one. ``None`` for first-contact emails with no thread history.
+    """
+
+    message_id: str
+    sender: str
+    recipient: str
+    raw_message: bytes
+    auth: AuthHeaders
+    received_at: Optional[datetime] = None
+    conversation_id: Optional[str] = None
+
+
+@dataclass
+class SendResult:
+    """Result from sending an email or reply."""
+
+    status: str
+    message_id: str
+    method: str  # "smtp" or "webhook"

e2a-0.1.0/src/e2a/webhook.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from datetime import datetime
+from typing import Any
+
+from e2a.models import AuthHeaders, WebhookPayload
+
+
+def verify_signature(body: bytes, signature: str, signing_key: str) -> bool:
+    """Verify the HMAC-SHA256 signature on a webhook request body.
+
+    Args:
+        body: Raw request body bytes.
+        signature: Value of the X-E2A-Webhook-Signature header.
+        signing_key: Your agent's signing key.
+
+    Returns:
+        True if the signature is valid.
+    """
+    expected = hmac.new(signing_key.encode(), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+def parse_payload(data: dict[str, Any], headers: dict[str, str]) -> WebhookPayload:
+    """Parse a webhook JSON body and request headers into a WebhookPayload.
+
+    Args:
+        data: Parsed JSON body from the webhook request.
+        headers: HTTP request headers (used for auth headers).
+
+    Returns:
+        A WebhookPayload with parsed fields.
+    """
+    raw_message = b""
+    if data.get("raw_message"):
+        try:
+            raw_message = base64.b64decode(data["raw_message"])
+        except Exception:
+            raw_message = data["raw_message"].encode() if isinstance(data["raw_message"], str) else b""
+
+    received_at = None
+    if data.get("received_at"):
+        try:
+            received_at = datetime.fromisoformat(data["received_at"].replace("Z", "+00:00"))
+        except (ValueError, AttributeError):
+            pass
+
+    return WebhookPayload(
+        message_id=data.get("message_id", ""),
+        sender=data.get("from", ""),
+        recipient=data.get("to", ""),
+        raw_message=raw_message,
+        auth=AuthHeaders.from_headers(headers),
+        received_at=received_at,
+        conversation_id=data.get("conversation_id"),
+    )

e2a-0.1.0/tests/test_client.py

@@ -0,0 +1,143 @@
+import json
+
+import httpx
+import pytest
+
+from e2a.client import E2AClient, E2AError
+
+
+def test_reply_success(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/messages/msg_123/reply",
+        method="POST",
+        json={"status": "sent", "message_id": "reply_456", "method": "smtp"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        result = client.reply("msg_123", "Thanks!")
+
+    assert result.status == "sent"
+    assert result.message_id == "reply_456"
+    assert result.method == "smtp"
+
+    request = httpx_mock.get_request()
+    assert request.headers["Authorization"] == "Bearer e2a_test"
+    body = json.loads(request.content)
+    assert body == {"body": "Thanks!"}
+
+
+def test_reply_with_html(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/messages/msg_123/reply",
+        method="POST",
+        json={"status": "sent", "message_id": "reply_789", "method": "smtp"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        result = client.reply("msg_123", "Thanks!", html_body="<p>Thanks!</p>")
+
+    body = json.loads(httpx_mock.get_request().content)
+    assert body == {"body": "Thanks!", "html_body": "<p>Thanks!</p>"}
+
+
+def test_reply_not_found(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/messages/msg_bad/reply",
+        method="POST",
+        status_code=404,
+        text="message not found",
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        with pytest.raises(E2AError) as exc_info:
+            client.reply("msg_bad", "Hello")
+
+    assert exc_info.value.status_code == 404
+    assert "message not found" in exc_info.value.message
+
+
+def test_send_success(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/send",
+        method="POST",
+        json={"status": "sent", "message_id": "send_abc", "method": "webhook"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        result = client.send("alice@example.com", "Hello", "Hi Alice")
+
+    assert result.status == "sent"
+    assert result.method == "webhook"
+
+    body = json.loads(httpx_mock.get_request().content)
+    assert body == {"to": "alice@example.com", "subject": "Hello", "body": "Hi Alice"}
+
+
+def test_send_unauthorized(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/send",
+        method="POST",
+        status_code=401,
+        text="unauthorized",
+    )
+
+    with E2AClient(api_key="bad_key", signing_key="sign_test") as client:
+        with pytest.raises(E2AError) as exc_info:
+            client.send("alice@example.com", "Hello", "Hi")
+
+    assert exc_info.value.status_code == 401
+
+
+def test_verify_webhook():
+    import hashlib
+    import hmac
+
+    body = b'{"from":"alice@example.com"}'
+    key = "sign_test"
+    sig = hmac.new(key.encode(), body, hashlib.sha256).hexdigest()
+
+    client = E2AClient(api_key="e2a_test", signing_key=key)
+    assert client.verify_webhook(body, sig) is True
+    assert client.verify_webhook(body, "wrong") is False
+    client.close()
+
+
+def test_reply_with_conversation_id(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/messages/msg_123/reply",
+        method="POST",
+        json={"status": "sent", "message_id": "reply_cid", "method": "smtp"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        result = client.reply("msg_123", "Thanks!", conversation_id="conv_abc")
+
+    body = json.loads(httpx_mock.get_request().content)
+    assert body == {"body": "Thanks!", "conversation_id": "conv_abc"}
+
+
+def test_send_with_conversation_id(httpx_mock):
+    httpx_mock.add_response(
+        url="https://e2a.dev/api/send",
+        method="POST",
+        json={"status": "sent", "message_id": "send_cid", "method": "smtp"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="sign_test") as client:
+        result = client.send("alice@example.com", "Hello", "Hi", conversation_id="conv_xyz")
+
+    body = json.loads(httpx_mock.get_request().content)
+    assert body["conversation_id"] == "conv_xyz"
+
+
+def test_custom_base_url(httpx_mock):
+    httpx_mock.add_response(
+        url="http://localhost:8080/api/send",
+        method="POST",
+        json={"status": "sent", "message_id": "local_123", "method": "smtp"},
+    )
+
+    with E2AClient(api_key="e2a_test", signing_key="s", base_url="http://localhost:8080") as client:
+        result = client.send("alice@example.com", "Test", "Body")
+
+    assert result.message_id == "local_123"

e2a-0.1.0/tests/test_webhook.py

@@ -0,0 +1,100 @@
+import hashlib
+import hmac
+
+from e2a.webhook import verify_signature, parse_payload
+
+
+def test_verify_signature_valid():
+    body = b'{"from":"alice@example.com"}'
+    key = "test-signing-key"
+    sig = hmac.new(key.encode(), body, hashlib.sha256).hexdigest()
+
+    assert verify_signature(body, sig, key) is True
+
+
+def test_verify_signature_invalid():
+    body = b'{"from":"alice@example.com"}'
+    assert verify_signature(body, "bad-signature", "test-key") is False
+
+
+def test_verify_signature_tampered_body():
+    body = b'{"from":"alice@example.com"}'
+    key = "test-key"
+    sig = hmac.new(key.encode(), body, hashlib.sha256).hexdigest()
+
+    tampered = b'{"from":"evil@example.com"}'
+    assert verify_signature(tampered, sig, key) is False
+
+
+def test_parse_payload_full():
+    data = {
+        "message_id": "msg_abc123",
+        "from": "alice@gmail.com",
+        "to": "bot@agent.example.com",
+        "raw_message": "SGVsbG8=",  # base64("Hello")
+        "received_at": "2026-03-22T10:30:00Z",
+    }
+    headers = {
+        "X-E2A-Auth-Verified": "true",
+        "X-E2A-Auth-Sender": "alice@gmail.com",
+        "X-E2A-Auth-Entity-Type": "human",
+        "X-E2A-Auth-Domain-Check": "spf=pass dkim=pass",
+        "X-E2A-Auth-Agent-Id": "agent_123",
+        "X-E2A-Auth-Human-Id": "human_456",
+    }
+
+    payload = parse_payload(data, headers)
+
+    assert payload.message_id == "msg_abc123"
+    assert payload.sender == "alice@gmail.com"
+    assert payload.recipient == "bot@agent.example.com"
+    assert payload.raw_message == b"Hello"
+    assert payload.received_at is not None
+    assert payload.auth.verified is True
+    assert payload.auth.sender == "alice@gmail.com"
+    assert payload.auth.entity_type == "human"
+    assert payload.auth.agent_id == "agent_123"
+    assert payload.auth.human_id == "human_456"
+
+
+def test_parse_payload_minimal():
+    data = {"from": "alice@gmail.com", "to": "bot@example.com"}
+    headers = {}
+
+    payload = parse_payload(data, headers)
+
+    assert payload.message_id == ""
+    assert payload.sender == "alice@gmail.com"
+    assert payload.raw_message == b""
+    assert payload.auth.verified is False
+
+
+def test_parse_payload_missing_message_id():
+    data = {"from": "alice@gmail.com", "to": "bot@example.com", "raw_message": "SGVsbG8="}
+    headers = {"X-E2A-Auth-Verified": "false"}
+
+    payload = parse_payload(data, headers)
+
+    assert payload.message_id == ""
+    assert payload.auth.verified is False
+
+
+def test_parse_payload_with_conversation_id():
+    data = {
+        "message_id": "msg_abc",
+        "conversation_id": "conv_123",
+        "from": "alice@gmail.com",
+        "to": "bot@example.com",
+    }
+
+    payload = parse_payload(data, {})
+
+    assert payload.conversation_id == "conv_123"
+
+
+def test_parse_payload_without_conversation_id():
+    data = {"from": "alice@gmail.com", "to": "bot@example.com"}
+
+    payload = parse_payload(data, {})
+
+    assert payload.conversation_id is None