mailsai 0.2.0__tar.gz → 0.2.2__tar.gz

{mailsai-0.2.0 → mailsai-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsai
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -38,29 +38,48 @@ 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`.
+No agent to create, no domain to verify, no DNS. `from` names the sender and the agent is
+created on first use.
 
 ```python
-from mailsai import Client, agent
+from mailsai import Client
 
 # 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.",
-)
+sent = client.send(**{
+    "from": "sarah",
+    "to": "you@example.com",
+    "subject": "Your verification code is 481902",
+    "body": "Your verification code is 481902. It expires in 15 minutes.",
+})
+
+print(sent["from"])   # sarah@<your-workspace>.mails.ai — which identity actually sent
+```
+
+A **test key** (`mk_test_…`) runs that entire path — validation, the firewall, threading,
+events, webhooks — and delivers nothing, so you can integrate before you decide anything. On a
+test key, check `sent.get("classifier_warning")`: it is how a sandbox send tells you the same
+message would be refused on a live key.
+
+Already have an agent, or want to name it explicitly? Both of these still work:
+
+```python
+client.create_agent("sarah")            # explicit creation, when you want it
+client.send("sarah", to="…", subject="…", body="…")
+```
+
+Note the free plan allows **one** agent. If `from` names a second one and there is no room,
+the send is refused with `402 plan_limit_exceeded` naming the agent you do have — it is never
+quietly sent under a different identity.
+
+```python
+from mailsai import agent
+
+sarah = agent("sarah")
 
 @sarah.on_reply
 def handle(reply):

{mailsai-0.2.0 → mailsai-0.2.2}/README.md

@@ -10,29 +10,48 @@ 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`.
+No agent to create, no domain to verify, no DNS. `from` names the sender and the agent is
+created on first use.
 
 ```python
-from mailsai import Client, agent
+from mailsai import Client
 
 # 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.",
-)
+sent = client.send(**{
+    "from": "sarah",
+    "to": "you@example.com",
+    "subject": "Your verification code is 481902",
+    "body": "Your verification code is 481902. It expires in 15 minutes.",
+})
+
+print(sent["from"])   # sarah@<your-workspace>.mails.ai — which identity actually sent
+```
+
+A **test key** (`mk_test_…`) runs that entire path — validation, the firewall, threading,
+events, webhooks — and delivers nothing, so you can integrate before you decide anything. On a
+test key, check `sent.get("classifier_warning")`: it is how a sandbox send tells you the same
+message would be refused on a live key.
+
+Already have an agent, or want to name it explicitly? Both of these still work:
+
+```python
+client.create_agent("sarah")            # explicit creation, when you want it
+client.send("sarah", to="…", subject="…", body="…")
+```
+
+Note the free plan allows **one** agent. If `from` names a second one and there is no room,
+the send is refused with `402 plan_limit_exceeded` naming the agent you do have — it is never
+quietly sent under a different identity.
+
+```python
+from mailsai import agent
+
+sarah = agent("sarah")
 
 @sarah.on_reply
 def handle(reply):

{mailsai-0.2.0 → mailsai-0.2.2}/mailsai/__init__.py

@@ -13,8 +13,11 @@ Quick start:
         # event["intent"]            -> "schedule_demo"
         # event["entities"]          -> {"date": "...", "time": "..."}
         # event["urgency"]           -> 0.8
-        # event["injection_score"]   -> 0.02
+        # event["injection_score"]   -> 0.02   (the evidence)
+        # event["quarantined"]       -> False  (our VERDICT — gate on this)
         # event["sender_reputation"] -> 0.91
+        if event.get("quarantined"):
+            return  # we judged it an attack; don't act on it
         print(event["intent"], event["entities"])
 
     sarah.start_listening()  # blocks; runs SSE consumer
@@ -206,14 +209,48 @@ class Client:
 
     # --- high-level helpers ---
 
-    def send(self, agent: str, **kwargs: Any) -> Dict[str, Any]:
-        """POST /api/v1/messages — send via a named agent."""
+    def send(self, agent: Optional[str] = None, **kwargs: Any) -> Dict[str, Any]:
+        """POST /api/v1/messages — send an email.
+
+        ``agent`` is OPTIONAL. Omit it and the workspace's single agent is used, or one is
+        created for you, named from ``from``::
+
+            client.send(**{"from": "billing", "to": "dana@acme.com",
+                           "subject": "Invoice #221", "body": "…"})
+
+        or name it explicitly, positionally or by keyword::
+
+            client.send("sarah", to="dana@acme.com", subject="…", body="…")
+
+        WHY THIS IS OPTIONAL NOW. ``agent`` was a required positional here long after the API
+        made it optional (2026-08-05), so the exact call our own positioning tells developers
+        to write — ``{from, to, subject, body}``, no setup — raised a TypeError in Python
+        before it ever reached the network, while the same call worked in TypeScript. Python
+        is the language of the agent ecosystem (both the OpenAI-Agents and LangGraph examples
+        are Python), so that gap fell on the users most likely to be the buyer.
+
+        ``from`` selects the agent by handle — ``"billing"``, ``"billing@acme.com"`` and
+        ``"Acme <billing@acme.com>"`` all mean the agent called ``billing``. It is resolved if
+        it exists, created if it does not, and refused with 402 ``plan_limit_exceeded`` if
+        your plan has no room; it is never resolved to a DIFFERENT agent. Read ``from`` on the
+        result for the address that actually sent.
+        """
         idempotency_key = kwargs.pop("idempotency_key", None)
-        kwargs["agent"] = agent
+        if agent is not 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 me(self) -> Dict[str, Any]:
+        """GET /api/v1/me — who this key is: workspace, tier, scopes, mode.
+
+        Present in the TypeScript SDK and exposed as an MCP tool; it was missing here, so a
+        Python caller had no way to answer "which workspace am I talking to, and is this key
+        live or test?" without a raw HTTP call.
+        """
+        return self._request("GET", "/api/v1/me")
+
     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)

{mailsai-0.2.0 → mailsai-0.2.2}/mailsai.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsai
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -38,29 +38,48 @@ 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`.
+No agent to create, no domain to verify, no DNS. `from` names the sender and the agent is
+created on first use.
 
 ```python
-from mailsai import Client, agent
+from mailsai import Client
 
 # 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.",
-)
+sent = client.send(**{
+    "from": "sarah",
+    "to": "you@example.com",
+    "subject": "Your verification code is 481902",
+    "body": "Your verification code is 481902. It expires in 15 minutes.",
+})
+
+print(sent["from"])   # sarah@<your-workspace>.mails.ai — which identity actually sent
+```
+
+A **test key** (`mk_test_…`) runs that entire path — validation, the firewall, threading,
+events, webhooks — and delivers nothing, so you can integrate before you decide anything. On a
+test key, check `sent.get("classifier_warning")`: it is how a sandbox send tells you the same
+message would be refused on a live key.
+
+Already have an agent, or want to name it explicitly? Both of these still work:
+
+```python
+client.create_agent("sarah")            # explicit creation, when you want it
+client.send("sarah", to="…", subject="…", body="…")
+```
+
+Note the free plan allows **one** agent. If `from` names a second one and there is no room,
+the send is refused with `402 plan_limit_exceeded` naming the agent you do have — it is never
+quietly sent under a different identity.
+
+```python
+from mailsai import agent
+
+sarah = agent("sarah")
 
 @sarah.on_reply
 def handle(reply):

{mailsai-0.2.0 → mailsai-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mailsai"
-version = "0.2.0"
+version = "0.2.2"
 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"