mailsai 0.1.1__tar.gz

mailsai-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mails.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailsai-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mailsai
+Version: 0.1.1
+Summary: Email API for AI agents — Python SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is opt-in.
+Author-email: "Mails.ai" <support@mails.ai>
+License: MIT
+Project-URL: Homepage, https://mails.ai
+Project-URL: Documentation, https://mails.ai/docs
+Project-URL: Source, https://github.com/RolloutsAI/mails-api
+Project-URL: Issues, https://github.com/RolloutsAI/mails-api/issues
+Keywords: email,ai,agent,mcp,mails.ai,agent-identity,sender-reputation,agent-email,prompt-injection,transactional-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# mailsai
+
+Email API for AI agents — Python SDK.
+
+Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Your agent reads the reply and decides what to say — intent + entity extraction is opt-in.
+
+```bash
+pip install mailsai
+```
+
+## Quick start
+
+Create the agent once (this mints its inbox address), then send from it. Skipping the
+create step is the most common first-run error — `agent("sarah")` only *references* an
+agent, it does not create one, so sending returns `404 agent_not_found`.
+
+```python
+from mailsai import Client, agent
+
+# Reads MAILS_API_KEY from env (or pass api_key=... explicitly)
+client = Client()
+
+# One-time setup: create the agent. It gets sarah@<your-workspace>.mails.ai
+client.create_agent("sarah")
+
+sarah = agent("sarah")
+
+# mails.ai is transactional-only: mail the recipient asked for. Cold outreach and bulk
+# marketing are refused with 422 cold_email_prohibited — that is deliberate, and it is
+# what keeps the sending reputation clean for everyone on the platform.
+sarah.send(
+    to="you@example.com",
+    subject="Your verification code is 481902",
+    body="Your verification code is 481902. It expires in 15 minutes.",
+)
+
+@sarah.on_reply
+def handle(reply):
+    # Always present — the delivery + security + identity layer:
+    # reply["injection_score"]   -> 0.02   # six-category prompt-injection scan
+    # reply["sender_reputation"] -> 0.91   # per-agent reputation
+    #
+    # Present only when classification is enabled (opt-in, +$0.003/inbound):
+    # reply["intent"]            -> "schedule_demo" | "ask_question" | …
+    # reply["entities"]          -> {"date": "...", "time": "..."}
+    # reply["urgency"]           -> 0.8
+    #
+    # Your agent reads the reply and decides what to send next.
+    print(reply["injection_score"], reply["sender_reputation"])
+
+sarah.start_listening()  # blocks; opens SSE stream and dispatches replies
+```
+
+For non-blocking, pass `blocking=False` to `start_listening()` — it returns a daemon thread.
+
+## Lower-level client
+
+```python
+from mailsai import create_client
+
+c = create_client()  # reads MAILS_API_KEY
+
+# Send via any agent
+c.send("sarah", to="lead@example.com", subject="Demo", body_text="…")
+
+# Resources
+threads = c.list_threads(agent_id="agent_abc123")
+usage = c.usage()
+rep = c.get_reputation(agent_id="agent_abc123")
+
+# Drafts
+draft = c.create_draft(agent="sarah", to="lead@example.com", subject="Demo", body_text="…")
+c.send_draft(draft["id"])
+```
+
+## Webhook verification
+
+```python
+from mailsai import verify_webhook
+
+# In your webhook handler:
+event = verify_webhook(
+    body=request.body.decode(),
+    signature=request.headers["X-Mails-Signature"],
+    secret=os.environ["MAILS_WEBHOOK_SECRET"],
+)
+if event is None:
+    return Response(status=400)
+# event is the verified inbound event dict
+```
+
+## Errors
+
+```python
+from mailsai import MailsError
+
+try:
+    sarah.send(to="blocked@example.com", subject="…", body="…")
+except MailsError as e:
+    print(e.type, e.code, e.message, e.status, e.request_id)
+```
+
+## Configuration
+
+| Param / env var | Default |
+|---|---|
+| `api_key` / `MAILS_API_KEY` | (required) |
+| `base_url` / `MAILS_BASE_URL` | `https://api.mails.ai` |
+
+## Documentation
+
+- Full docs: [mails.ai/docs](https://mails.ai/docs)
+- Source: [github.com/RolloutsAI/mails-api](https://github.com/RolloutsAI/mails-api/tree/main/packages/sdk-py)
+
+## License
+
+MIT

mailsai-0.1.1/README.md

@@ -0,0 +1,117 @@
+# mailsai
+
+Email API for AI agents — Python SDK.
+
+Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Your agent reads the reply and decides what to say — intent + entity extraction is opt-in.
+
+```bash
+pip install mailsai
+```
+
+## Quick start
+
+Create the agent once (this mints its inbox address), then send from it. Skipping the
+create step is the most common first-run error — `agent("sarah")` only *references* an
+agent, it does not create one, so sending returns `404 agent_not_found`.
+
+```python
+from mailsai import Client, agent
+
+# Reads MAILS_API_KEY from env (or pass api_key=... explicitly)
+client = Client()
+
+# One-time setup: create the agent. It gets sarah@<your-workspace>.mails.ai
+client.create_agent("sarah")
+
+sarah = agent("sarah")
+
+# mails.ai is transactional-only: mail the recipient asked for. Cold outreach and bulk
+# marketing are refused with 422 cold_email_prohibited — that is deliberate, and it is
+# what keeps the sending reputation clean for everyone on the platform.
+sarah.send(
+    to="you@example.com",
+    subject="Your verification code is 481902",
+    body="Your verification code is 481902. It expires in 15 minutes.",
+)
+
+@sarah.on_reply
+def handle(reply):
+    # Always present — the delivery + security + identity layer:
+    # reply["injection_score"]   -> 0.02   # six-category prompt-injection scan
+    # reply["sender_reputation"] -> 0.91   # per-agent reputation
+    #
+    # Present only when classification is enabled (opt-in, +$0.003/inbound):
+    # reply["intent"]            -> "schedule_demo" | "ask_question" | …
+    # reply["entities"]          -> {"date": "...", "time": "..."}
+    # reply["urgency"]           -> 0.8
+    #
+    # Your agent reads the reply and decides what to send next.
+    print(reply["injection_score"], reply["sender_reputation"])
+
+sarah.start_listening()  # blocks; opens SSE stream and dispatches replies
+```
+
+For non-blocking, pass `blocking=False` to `start_listening()` — it returns a daemon thread.
+
+## Lower-level client
+
+```python
+from mailsai import create_client
+
+c = create_client()  # reads MAILS_API_KEY
+
+# Send via any agent
+c.send("sarah", to="lead@example.com", subject="Demo", body_text="…")
+
+# Resources
+threads = c.list_threads(agent_id="agent_abc123")
+usage = c.usage()
+rep = c.get_reputation(agent_id="agent_abc123")
+
+# Drafts
+draft = c.create_draft(agent="sarah", to="lead@example.com", subject="Demo", body_text="…")
+c.send_draft(draft["id"])
+```
+
+## Webhook verification
+
+```python
+from mailsai import verify_webhook
+
+# In your webhook handler:
+event = verify_webhook(
+    body=request.body.decode(),
+    signature=request.headers["X-Mails-Signature"],
+    secret=os.environ["MAILS_WEBHOOK_SECRET"],
+)
+if event is None:
+    return Response(status=400)
+# event is the verified inbound event dict
+```
+
+## Errors
+
+```python
+from mailsai import MailsError
+
+try:
+    sarah.send(to="blocked@example.com", subject="…", body="…")
+except MailsError as e:
+    print(e.type, e.code, e.message, e.status, e.request_id)
+```
+
+## Configuration
+
+| Param / env var | Default |
+|---|---|
+| `api_key` / `MAILS_API_KEY` | (required) |
+| `base_url` / `MAILS_BASE_URL` | `https://api.mails.ai` |
+
+## Documentation
+
+- Full docs: [mails.ai/docs](https://mails.ai/docs)
+- Source: [github.com/RolloutsAI/mails-api](https://github.com/RolloutsAI/mails-api/tree/main/packages/sdk-py)
+
+## License
+
+MIT

mailsai-0.1.1/mailsai/__init__.py

@@ -0,0 +1,499 @@
+"""
+Mails.ai — Email API for AI agents (Python SDK).
+
+Quick start:
+
+    from mailsai import agent
+
+    sarah = agent("sarah")  # sarah@yourcompany.mails.ai
+    sarah.send(to="lead@example.com", subject="Demo", body="Hi…")
+
+    @sarah.on_reply
+    def handle(event):
+        # event["intent"]            -> "schedule_demo"
+        # event["entities"]          -> {"date": "...", "time": "..."}
+        # event["urgency"]           -> 0.8
+        # event["injection_score"]   -> 0.02
+        # event["sender_reputation"] -> 0.91
+        print(event["intent"], event["entities"])
+
+    sarah.start_listening()  # blocks; runs SSE consumer
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import uuid
+import os
+import sys
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional, Union
+from urllib.parse import urlencode
+
+try:
+    import httpx  # type: ignore
+except ImportError:  # pragma: no cover
+    httpx = None  # streaming + main client both require httpx
+
+# Single source of truth is pyproject.toml. A hardcoded literal here silently drifted on
+# the first version bump (metadata said 0.1.1, this said 0.1.0) and it rides the
+# User-Agent header, so the drift also misreports the client version server-side.
+try:  # installed normally
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    __version__ = _pkg_version("mailsai")
+except Exception:  # running from a source checkout, or metadata unavailable
+    __version__ = "0.1.1"
+__all__ = [
+    "agent",
+    "Agent",
+    "Client",
+    "MailsError",
+    "verify_webhook",
+    "create_client",
+    "__version__",
+]
+
+DEFAULT_BASE = "https://api.mails.ai"
+DEFAULT_TIMEOUT = 30.0
+# Bounded exponential backoff for transient failures (429 / retry-safe 5xx).
+_MAX_RETRIES = 3
+_RETRY_BASE = 0.5
+_RETRY_CAP = 8.0
+
+
+class MailsError(Exception):
+    """Raised on any non-2xx response from the Mails.ai API."""
+
+    def __init__(
+        self,
+        type: str,
+        code: str,
+        message: str,
+        status: int = 0,
+        request_id: Optional[str] = None,
+        param: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.type = type
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.param = param
+
+
+def _require_httpx() -> Any:
+    if httpx is None:
+        raise RuntimeError(
+            "The mailsai Python SDK requires httpx. Install it with: pip install 'mailsai[http]' "
+            "or pip install httpx"
+        )
+    return httpx
+
+
+class Client:
+    """Low-level Mails.ai REST client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.api_key = api_key or os.environ.get("MAILS_API_KEY") or ""
+        self.base_url = (base_url or os.environ.get("MAILS_BASE_URL") or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+        if not self.api_key:
+            raise MailsError(
+                "invalid_request_error",
+                "missing_api_key",
+                "MAILS_API_KEY env var or api_key argument required.",
+            )
+
+    def _headers(self, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        h = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"mailsai-python/{__version__}",
+        }
+        if extra:
+            h.update(extra)
+        return h
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        httpx_mod = _require_httpx()
+        url = f"{self.base_url}{path}"
+        merged_headers = self._headers(headers)
+        data = json.dumps(body).encode() if body is not None else None
+        # Retry-safe when a resend can't double-apply: a 429 was rejected (never
+        # processed); 5xx only for read methods or when an Idempotency-Key makes a
+        # resend a server-side no-op.
+        idempotent_method = method in ("GET", "HEAD")
+        has_idem_key = any(k.lower() == "idempotency-key" for k in merged_headers)
+        # A POST that reaches the server may be PROCESSED even if we never see the
+        # response (timeout, dropped connection). Without an Idempotency-Key the caller's
+        # natural reaction — retry — sends the email twice. Generate one so a resend is a
+        # server-side no-op. Callers who pass their own key keep full control.
+        if method == "POST" and not has_idem_key:
+            merged_headers["Idempotency-Key"] = f"sdk-{uuid.uuid4()}"
+            has_idem_key = True
+
+        attempt = 0
+        while True:
+            try:
+                r = httpx_mod.request(
+                    method, url, headers=merged_headers, content=data, timeout=self.timeout
+                )
+            except Exception as exc:  # httpx.TimeoutException, ConnectError, …
+                # Never leak a raw httpx traceback: callers catch MailsError, and a bare
+                # transport exception carries no request id and no guidance on whether the
+                # call landed. Retry only when a resend cannot double-apply.
+                if attempt < _MAX_RETRIES and (idempotent_method or has_idem_key):
+                    time.sleep(min(_RETRY_CAP, _RETRY_BASE * (2 ** attempt)))
+                    attempt += 1
+                    continue
+                raise MailsError(
+                    "connection_error",
+                    "transport_error",
+                    f"{method} {path} could not complete: {exc}. The request may or may "
+                    "not have been processed — retry with the same Idempotency-Key rather "
+                    "than issuing a fresh call.",
+                    None,
+                    None,
+                    None,
+                ) from exc
+            request_id = r.headers.get("x-request-id")
+            if 200 <= r.status_code < 300:
+                if r.status_code == 204:
+                    return None
+                return r.json()
+            retryable = attempt < _MAX_RETRIES and (
+                r.status_code == 429
+                or (r.status_code >= 500 and (idempotent_method or has_idem_key))
+            )
+            if retryable:
+                try:
+                    retry_after = float(r.headers.get("retry-after", ""))
+                except (TypeError, ValueError):
+                    retry_after = 0.0
+                wait = retry_after if retry_after > 0 else min(_RETRY_CAP, _RETRY_BASE * (2 ** attempt))
+                time.sleep(wait)
+                attempt += 1
+                continue
+            try:
+                payload = r.json()
+            except (ValueError, json.JSONDecodeError):
+                payload = {}
+            err = payload.get("error", {}) if isinstance(payload, dict) else {}
+            raise MailsError(
+                err.get("type", "api_error"),
+                err.get("code", "unknown"),
+                err.get("message", f"{method} {path} failed with {r.status_code}"),
+                r.status_code,
+                request_id,
+                err.get("param"),
+            )
+
+    # --- high-level helpers ---
+
+    def send(self, agent: str, **kwargs: Any) -> Dict[str, Any]:
+        """POST /api/v1/messages — send via a named agent."""
+        idempotency_key = kwargs.pop("idempotency_key", None)
+        kwargs["agent"] = agent
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self._request("POST", "/api/v1/messages", body, headers)
+
+    def reply(self, message_id: str, **kwargs: Any) -> Dict[str, Any]:
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        return self._request("POST", f"/api/v1/messages/{message_id}/reply", body)
+
+    def forward(self, message_id: str, **kwargs: Any) -> Dict[str, Any]:
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        return self._request("POST", f"/api/v1/messages/{message_id}/forward", body)
+
+    def list_threads(self, **opts: Any) -> Dict[str, Any]:
+        qs = "?" + urlencode({k: v for k, v in opts.items() if v is not None}) if opts else ""
+        return self._request("GET", f"/api/v1/threads{qs}")
+
+    def get_thread(self, thread_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/threads/{thread_id}")
+
+    def list_received(self, **opts: Any) -> Dict[str, Any]:
+        qs = "?" + urlencode({k: v for k, v in opts.items() if v is not None}) if opts else ""
+        return self._request("GET", f"/api/v1/messages/received{qs}")
+
+    def get_received(self, id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/messages/received/{id}")
+
+    def list_agents(self, **opts: Any) -> Dict[str, Any]:
+        qs = "?" + urlencode({k: v for k, v in opts.items() if v is not None}) if opts else ""
+        return self._request("GET", f"/api/v1/agents{qs}")
+
+    def create_agent(
+        self,
+        name: str,
+        domain: Optional[str] = None,
+        allowlist_domains: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        body = {"name": name}
+        if domain:
+            body["domain"] = domain
+        if allowlist_domains:
+            body["allowlist_domains"] = allowlist_domains
+        return self._request("POST", "/api/v1/agents", body)
+
+    def list_events(self, **opts: Any) -> Dict[str, Any]:
+        qs = "?" + urlencode({k: v for k, v in opts.items() if v is not None}) if opts else ""
+        return self._request("GET", f"/api/v1/events{qs}")
+
+    def get_event(self, event_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/v1/events/{event_id}")
+
+    def get_reputation(self, agent_id: Optional[str] = None) -> Dict[str, Any]:
+        qs = "?" + urlencode({"agent_id": agent_id}) if agent_id else ""
+        return self._request("GET", f"/api/v1/reputation{qs}")
+
+    def check_suppression(self, address: str) -> Dict[str, Any]:
+        return self._request("GET", "/api/v1/suppression?" + urlencode({"address": address}))
+
+    def allow_address(self, address: str, attestation: str) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/suppression/allow", {"address": address, "attestation": attestation})
+
+    def create_draft(self, **kwargs: Any) -> Dict[str, Any]:
+        body = {k: v for k, v in kwargs.items() if v is not None}
+        return self._request("POST", "/api/v1/drafts", body)
+
+    def send_draft(self, draft_id: str, send_at: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {}
+        if send_at is not None:
+            body["send_at"] = send_at
+        return self._request("POST", f"/api/v1/drafts/{draft_id}/send", body)
+
+    def usage(self) -> Dict[str, Any]:
+        return self._request("GET", "/api/v1/billing/usage")
+
+    def stream_events(
+        self,
+        event_types: Optional[List[str]] = None,
+        since: Optional[str] = None,
+        on_event: Optional[Callable[[Dict[str, Any]], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        stop_event: Optional[threading.Event] = None,
+    ) -> None:
+        """Blocking SSE consumer. Pass stop_event to break the loop from another thread."""
+        httpx_mod = _require_httpx()
+        params: Dict[str, str] = {}
+        if event_types:
+            params["event_types"] = ",".join(event_types)
+        if since:
+            params["since"] = since
+        qs = ("?" + urlencode(params)) if params else ""
+        url = f"{self.base_url}/api/v1/events/stream{qs}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "text/event-stream",
+            "User-Agent": f"mailsai-python/{__version__}",
+        }
+        try:
+            with httpx_mod.stream("GET", url, headers=headers, timeout=None) as r:
+                r.raise_for_status()
+                for line in r.iter_lines():
+                    if stop_event is not None and stop_event.is_set():
+                        return
+                    if not line or not line.startswith("data: "):
+                        continue
+                    try:
+                        evt = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+                    if on_event is not None:
+                        on_event(evt)
+        except Exception as e:  # noqa: BLE001
+            if on_error is not None:
+                on_error(e)
+            else:
+                raise
+
+
+class Agent:
+    """A named agent. Pass an existing Client or omit to auto-construct from env."""
+
+    def __init__(self, client: Client, name: str, domain: Optional[str] = None):
+        self._client = client
+        self.name = name
+        self._domain = domain
+        self._reply_handlers: List[Callable[[Dict[str, Any]], None]] = []
+        self._id: Optional[str] = None
+        self._stop_event: Optional[threading.Event] = None
+
+    @property
+    def client(self) -> Client:
+        return self._client
+
+    def send(
+        self,
+        to: Union[str, List[str]],
+        subject: str,
+        body: Optional[str] = None,
+        body_text: Optional[str] = None,
+        body_html: Optional[str] = None,
+        cc: Optional[List[str]] = None,
+        bcc: Optional[List[str]] = None,
+        reply_to: Optional[str] = None,
+        in_reply_to_message_id: Optional[str] = None,
+        scheduled_at: Optional[str] = None,
+        tags: Optional[List[Dict[str, str]]] = None,
+        metadata: Optional[Dict[str, str]] = None,
+        pool_hint: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        return self._client.send(
+            self.name,
+            to=to,
+            subject=subject,
+            body_text=body_text or body,
+            body_html=body_html,
+            cc=cc,
+            bcc=bcc,
+            reply_to=reply_to,
+            in_reply_to_message_id=in_reply_to_message_id,
+            scheduled_at=scheduled_at,
+            tags=tags,
+            metadata=metadata,
+            pool_hint=pool_hint,
+            idempotency_key=idempotency_key,
+        )
+
+    def on_reply(self, handler: Callable[[Dict[str, Any]], None]) -> Callable[[Dict[str, Any]], None]:
+        """Decorator. Register a callback for reply.received events for this agent.
+
+        Call agent.start_listening() to begin SSE consumption.
+        """
+        self._reply_handlers.append(handler)
+        return handler
+
+    def list_replies(self, limit: int = 10, since: Optional[str] = None) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"event_type": "reply.received", "agent_id": self.name, "limit": limit}
+        if since is not None:
+            params["since"] = since
+        return self._client.list_events(**params)
+
+    def reputation(self) -> Dict[str, Any]:
+        return self._client.get_reputation(agent_id=self.name)
+
+    def _resolve_id(self) -> str:
+        if self._id is not None:
+            return self._id
+        rows = self._client.list_agents(limit=100)
+        for row in rows.get("data", []):
+            if row.get("name") == self.name:
+                self._id = row["id"]
+                return self._id
+        raise MailsError(
+            "resource_error",
+            "agent_not_found",
+            f'Agent "{self.name}" not found. Create it with client.create_agent("{self.name}") first.',
+        )
+
+    def start_listening(self, blocking: bool = True) -> Optional[threading.Thread]:
+        """Begin consuming reply.received events and dispatch to @on_reply handlers.
+
+        blocking=True (default) blocks the calling thread. blocking=False spawns a
+        daemon thread; returns the thread for caller to join().
+        """
+        if not self._reply_handlers:
+            raise RuntimeError("No reply handlers registered. Use @agent.on_reply first.")
+        if self._stop_event is None:
+            self._stop_event = threading.Event()
+
+        def _loop() -> None:
+            try:
+                agent_id = self._resolve_id()
+            except Exception as e:  # noqa: BLE001
+                for h in self._reply_handlers:
+                    print(f"[mailsai] resolve_id failed: {e}", file=sys.stderr)
+                return
+
+            def _on_event(evt: Dict[str, Any]) -> None:
+                if evt.get("agent_id") != agent_id:
+                    return
+                for h in self._reply_handlers:
+                    try:
+                        h(evt)
+                    except Exception as exc:  # noqa: BLE001
+                        print(f"[mailsai] handler error: {exc}", file=sys.stderr)
+
+            def _on_error(e: Exception) -> None:
+                print(f"[mailsai] stream error: {e}", file=sys.stderr)
+
+            self._client.stream_events(
+                event_types=["reply.received"],
+                on_event=_on_event,
+                on_error=_on_error,
+                stop_event=self._stop_event,
+            )
+
+        if blocking:
+            _loop()
+            return None
+        t = threading.Thread(target=_loop, daemon=True, name=f"mailsai-stream-{self.name}")
+        t.start()
+        return t
+
+    def stop_listening(self) -> None:
+        if self._stop_event is not None:
+            self._stop_event.set()
+
+
+def create_client(api_key: Optional[str] = None, base_url: Optional[str] = None) -> Client:
+    """Return a low-level Client. Use this when you need full API access."""
+    return Client(api_key=api_key, base_url=base_url)
+
+
+def agent(
+    name: str,
+    domain: Optional[str] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Agent:
+    """Create an Agent. Reuses one Client per call; pass api_key or set MAILS_API_KEY."""
+    return Agent(Client(api_key=api_key, base_url=base_url), name, domain)
+
+
+def verify_webhook(
+    body: str,
+    signature: str,
+    secret: str,
+    tolerance_sec: int = 300,
+) -> Optional[Dict[str, Any]]:
+    """Verify a webhook signature header (Stripe-style t=<ts>,v1=<hex>).
+
+    Returns the parsed event dict if valid, None if invalid (expired, bad MAC,
+    or malformed). Use this in your webhook handler before trusting the body.
+    """
+    try:
+        parts = dict(p.split("=", 1) for p in signature.split(",") if "=" in p)
+        ts = int(parts.get("t", "0"))
+        if abs(int(time.time()) - ts) > tolerance_sec:
+            return None
+        expected = hmac.new(
+            secret.encode(),
+            f"{ts}.{body}".encode(),
+            hashlib.sha256,
+        ).hexdigest()
+        if not hmac.compare_digest(expected, parts.get("v1", "")):
+            return None
+        return json.loads(body)
+    except (ValueError, KeyError, json.JSONDecodeError):
+        return None

mailsai-0.1.1/mailsai.egg-info/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mailsai
+Version: 0.1.1
+Summary: Email API for AI agents — Python SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is opt-in.
+Author-email: "Mails.ai" <support@mails.ai>
+License: MIT
+Project-URL: Homepage, https://mails.ai
+Project-URL: Documentation, https://mails.ai/docs
+Project-URL: Source, https://github.com/RolloutsAI/mails-api
+Project-URL: Issues, https://github.com/RolloutsAI/mails-api/issues
+Keywords: email,ai,agent,mcp,mails.ai,agent-identity,sender-reputation,agent-email,prompt-injection,transactional-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# mailsai
+
+Email API for AI agents — Python SDK.
+
+Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Your agent reads the reply and decides what to say — intent + entity extraction is opt-in.
+
+```bash
+pip install mailsai
+```
+
+## Quick start
+
+Create the agent once (this mints its inbox address), then send from it. Skipping the
+create step is the most common first-run error — `agent("sarah")` only *references* an
+agent, it does not create one, so sending returns `404 agent_not_found`.
+
+```python
+from mailsai import Client, agent
+
+# Reads MAILS_API_KEY from env (or pass api_key=... explicitly)
+client = Client()
+
+# One-time setup: create the agent. It gets sarah@<your-workspace>.mails.ai
+client.create_agent("sarah")
+
+sarah = agent("sarah")
+
+# mails.ai is transactional-only: mail the recipient asked for. Cold outreach and bulk
+# marketing are refused with 422 cold_email_prohibited — that is deliberate, and it is
+# what keeps the sending reputation clean for everyone on the platform.
+sarah.send(
+    to="you@example.com",
+    subject="Your verification code is 481902",
+    body="Your verification code is 481902. It expires in 15 minutes.",
+)
+
+@sarah.on_reply
+def handle(reply):
+    # Always present — the delivery + security + identity layer:
+    # reply["injection_score"]   -> 0.02   # six-category prompt-injection scan
+    # reply["sender_reputation"] -> 0.91   # per-agent reputation
+    #
+    # Present only when classification is enabled (opt-in, +$0.003/inbound):
+    # reply["intent"]            -> "schedule_demo" | "ask_question" | …
+    # reply["entities"]          -> {"date": "...", "time": "..."}
+    # reply["urgency"]           -> 0.8
+    #
+    # Your agent reads the reply and decides what to send next.
+    print(reply["injection_score"], reply["sender_reputation"])
+
+sarah.start_listening()  # blocks; opens SSE stream and dispatches replies
+```
+
+For non-blocking, pass `blocking=False` to `start_listening()` — it returns a daemon thread.
+
+## Lower-level client
+
+```python
+from mailsai import create_client
+
+c = create_client()  # reads MAILS_API_KEY
+
+# Send via any agent
+c.send("sarah", to="lead@example.com", subject="Demo", body_text="…")
+
+# Resources
+threads = c.list_threads(agent_id="agent_abc123")
+usage = c.usage()
+rep = c.get_reputation(agent_id="agent_abc123")
+
+# Drafts
+draft = c.create_draft(agent="sarah", to="lead@example.com", subject="Demo", body_text="…")
+c.send_draft(draft["id"])
+```
+
+## Webhook verification
+
+```python
+from mailsai import verify_webhook
+
+# In your webhook handler:
+event = verify_webhook(
+    body=request.body.decode(),
+    signature=request.headers["X-Mails-Signature"],
+    secret=os.environ["MAILS_WEBHOOK_SECRET"],
+)
+if event is None:
+    return Response(status=400)
+# event is the verified inbound event dict
+```
+
+## Errors
+
+```python
+from mailsai import MailsError
+
+try:
+    sarah.send(to="blocked@example.com", subject="…", body="…")
+except MailsError as e:
+    print(e.type, e.code, e.message, e.status, e.request_id)
+```
+
+## Configuration
+
+| Param / env var | Default |
+|---|---|
+| `api_key` / `MAILS_API_KEY` | (required) |
+| `base_url` / `MAILS_BASE_URL` | `https://api.mails.ai` |
+
+## Documentation
+
+- Full docs: [mails.ai/docs](https://mails.ai/docs)
+- Source: [github.com/RolloutsAI/mails-api](https://github.com/RolloutsAI/mails-api/tree/main/packages/sdk-py)
+
+## License
+
+MIT

mailsai-0.1.1/mailsai.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+mailsai/__init__.py
+mailsai.egg-info/PKG-INFO
+mailsai.egg-info/SOURCES.txt
+mailsai.egg-info/dependency_links.txt
+mailsai.egg-info/requires.txt
+mailsai.egg-info/top_level.txt

mailsai-0.1.1/mailsai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mailsai-0.1.1/mailsai.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24.0

mailsai-0.1.1/mailsai.egg-info/top_level.txt

@@ -0,0 +1 @@
+mailsai

mailsai-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mailsai"
+version = "0.1.1"
+description = "Email API for AI agents — Python SDK. Per-agent email addresses on your domain, per-agent reputation, and prompt-injection scanning on every inbound. Send, receive structured inbound replies, and identify agents via REST. Intent + entity extraction is opt-in."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Mails.ai", email = "support@mails.ai" }]
+keywords = ["email", "ai", "agent", "mcp", "mails.ai", "agent-identity", "sender-reputation", "agent-email", "prompt-injection", "transactional-email"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Email",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.24.0"]
+
+[project.urls]
+Homepage = "https://mails.ai"
+Documentation = "https://mails.ai/docs"
+Source = "https://github.com/RolloutsAI/mails-api"
+Issues = "https://github.com/RolloutsAI/mails-api/issues"
+
+[tool.setuptools]
+packages = ["mailsai"]

mailsai-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+