agent-email-guard 0.1.0__tar.gz

agent_email_guard-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.venv39/

agent_email_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentiSend
+
+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.

agent_email_guard-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: agent-email-guard
+Version: 0.1.0
+Summary: Blast-radius control for agents that send email: budgets, a rate ceiling, loop detection, approval holds and a kill switch, in front of any provider.
+Project-URL: Homepage, https://agentisend.com
+Project-URL: Source, https://github.com/agentisend/agent-email-guard
+Project-URL: Issues, https://github.com/agentisend/agent-email-guard/issues
+Author-email: AgentiSend <hello@agentisend.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,budget,email,guardrails,kill-switch,loop-detection,mcp,rate-limit,resend-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: fakeredis[lua]>=2.20; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg>=3.1; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=4.2; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# agent-email-guard
+
+Blast-radius control for agents that send email. It caps how much an agent can send and to whom, stops loops, holds chosen sends for a person, and gives you one call that stops everything. It works in front of any provider: AgentiSend, Resend, Amazon SES, SMTP, or your own function.
+
+It limits volume, repetition and recipients. It does not read intent or detect prompt injection; an agent tricked into sending one bad email within its limits still sends it.
+
+```bash
+pip install agent-email-guard
+```
+
+Python 3.9 or newer. No runtime dependencies. Redis and Postgres stores are optional extras.
+
+## Twelve lines
+
+```python
+from agent_email_guard import ApprovalRequired, Guard, GuardRefused
+
+guard = Guard(
+    budgets={"per_hour": 50, "per_day": 500},
+    rate={"per_minute": 10},
+    suppress=["@competitor.example"],
+)
+send = guard.wrap(provider.send)  # any function that takes one email dict
+
+try:
+    send({"to": "customer@example.com", "subject": "Your receipt", "text": "Thanks."})
+except (GuardRefused, ApprovalRequired) as stop:
+    print(stop.decision.reason, stop.decision.message)
+```
+
+`wrap()` keeps the function's signature. Each call is checked, sent, and recorded. If the provider raises, the reservation is given back and the provider's error reaches you unchanged.
+
+## What it decides
+
+Every check returns a `Decision` with four fields. `outcome` is `allow`, `hold_for_approval` or `refuse`. `reason` is a stable token. `message` is one sentence a person can read. `evidence` holds the numbers behind it:
+
+```python
+>>> guard.check({"to": "ops@example.com", "subject": "Disk at 91%", "text": "db-1"})
+Decision(outcome='refuse', reason='loop_repetition_detected',
+         message='Blocked: 3 near-identical emails already went to ops@example.com within 60 minutes, which matches a retry or script loop; review the agent before sending more.',
+         evidence={'matching_sends_in_window': 3, 'repetition_threshold': 3, 'window_ms': 3600000, ...})
+```
+
+Checks run in this order and stop at the first block:
+
+| # | Check | Outcome | Reason |
+|---|---|---|---|
+| 1 | Kill switch | refuse | `kill_switch_active` |
+| 2 | Suppression list | refuse | `recipient_suppressed` |
+| 3 | Loop detection | refuse | `loop_repetition_detected`, `recipient_entropy_collapse` |
+| 4 | Approval rules | hold | `recipient_requires_approval` |
+| 5 | Rate ceiling (sliding minute) | refuse | `rate_ceiling_exceeded` |
+| 6 | Budgets (UTC hour, day, month) | refuse | `agent_budget_exceeded` |
+| 7 | | allow | `ok` |
+
+Steps 1 to 4 reserve nothing. Steps 5 and 6 reserve atomically: 200 concurrent checks against a budget of 50 allow exactly 50 (the test suite runs this with threads and with asyncio).
+
+**Loop detection** uses two signals. The first is repetition: the agent has already sent 3 emails to the same To line within 60 minutes, with subject and body at least 85% similar (trigram Jaccard). The second is recipient collapse: across 20 or more recent sends, the effective number of recipients has dropped below 3. A collapsed window holds only a send to one of the inboxes it collapsed on. A sign-in code to a new user still goes out. Both signals and all five thresholds are configurable (`LOOP_DEFAULTS`). `loop={"mode": "repetition_only"}` turns off the collapse signal, and `loop=False` turns off both.
+
+**Approvals.** `approval={"recipients": ["@bigcustomer.com"]}` holds any send to that domain. `approval={"new_recipients": True}` holds a send to any address this key has never sent to. `approval={"require_for": fn}` holds a send whenever your function returns something truthy. Keep held sends wherever you like, then call `stop.approve()` once a person says yes. Every other check runs again before the email goes out.
+
+**Kill switch.** `guard.kill_switch.pause("looping on one inbox", by="ops")` stops every send through this guard, for every key, until someone calls `guard.kill_switch.resume("ops")`. There is no timer. A paused guard is still paused a year later.
+
+**Keys.** A send can name the agent it belongs to with `"key": "billing-agent"`. Each key gets its own budget, rate window, loop window and seen-recipient memory.
+
+## Policy file
+
+Keep the limits in `agent-email-guard.json` next to your code instead of inside it. The same file configures the Node, PHP and Go ports. An unknown key or a wrong type rejects the whole file with a sentence naming the key.
+
+```json
+{
+  "version": 1,
+  "key": "support-agent",
+  "budgets": {"per_hour": 50, "per_day": 500},
+  "rate": {"per_minute": 10},
+  "approval": {"new_recipients": true, "recipients": ["@bigcustomer.com"]},
+  "suppress": ["@competitor.example"]
+}
+```
+
+```python
+guard = Guard.from_policy()                       # reads ./agent-email-guard.json
+guard = Guard.from_policy("config/agent-email-guard.json", require_for=my_rule, store=store)
+```
+
+`require_for` is code, so it is passed in, never read from the file. Keyword arguments override the file.
+
+## Advisory here, enforced at AgentiSend
+
+This library runs inside the agent's own process. That makes it advisory. An agent that edits its own code, skips `check()`, or starts a second process with a fresh in-memory store can get around it. For many teams that is enough: the failure it catches is the agent stuck in a retry loop, not an agent fighting its operator.
+
+When you need limits the agent cannot remove, AgentiSend enforces the same rules at its API, on the API key itself. The rules are budget, per-minute ceiling, loop detection, approval queue and kill switch. Every process using that key shares them, and a paused key cannot resume itself: only a person signed in to the console can.
+
+```python
+from agent_email_guard.agentisend import AgentiSendGuard
+
+hosted = AgentiSendGuard(key_id="your-api-key-id")   # reads AGENTISEND_API_KEY
+hosted.apply_limits(budgets={"per_day": 500}, rate={"per_minute": 10})
+hosted.check(email)        # POST /emails/preflight: runs every gate, sends nothing
+hosted.send(email)         # POST /emails: raises GuardRefused / ApprovalRequired like the local guard
+hosted.kill_switch.pause("looping")
+hosted.approvals.list()    # held sends waiting for a person
+```
+
+A key can lower its own limits. Raising a limit is a person's decision, made in the console.
+
+## Integrations
+
+Each one is a runnable file in [`examples/`](examples/). The test suite runs every example against a stub.
+
+- **AgentiSend** ([`agentisend_sdk.py`](examples/agentisend_sdk.py)): `guard.wrap(AgentiSend().send_email)`, with the hosted adapter above for enforcement.
+- **Resend** ([`resend_sdk.py`](examples/resend_sdk.py)): `guard.wrap(resend.Emails.send)`.
+- **Amazon SES** ([`boto3_ses.py`](examples/boto3_ses.py)): `guard.wrap(ses.send_email, extract=...)`, which maps SES's keyword arguments to a send.
+- **SMTP** ([`smtp_stdlib.py`](examples/smtp_stdlib.py)): `smtplib` and `email.message`, standard library only.
+- **LangChain and the OpenAI Agents SDK** ([`agent_tool.py`](examples/agent_tool.py)): a `send_email` tool that returns the guard's sentence instead of raising. The model reads why a send was refused and does not retry in a loop.
+
+## Sharing limits across processes
+
+The in-memory store counts for one process. To share budgets, the rate window, the loop log and the kill switch across processes, use one of these:
+
+```python
+# pip install "agent-email-guard[redis]"
+import redis
+from agent_email_guard.stores.redis import RedisStore
+guard = Guard(budgets={"per_day": 500}, store=RedisStore(redis.Redis.from_url("redis://localhost:6379/0")))
+
+# pip install "agent-email-guard[postgres]"
+import psycopg
+from agent_email_guard.stores.postgres import PostgresStore
+store = PostgresStore(psycopg.connect("postgresql://localhost/app", autocommit=True))
+store.setup()  # creates four agent_email_guard_* tables if missing
+guard = Guard(budgets={"per_day": 500}, store=store)
+```
+
+Redis runs every check-and-reserve as one Lua script. Postgres uses one conditional upsert per counter, plus an advisory lock around the rate window. Store key names are shared with the Node, PHP and Go ports of agent-email-guard, so agents written in different languages can share one budget.
+
+## asyncio
+
+```python
+from agent_email_guard import AsyncGuard
+from agent_email_guard.stores.redis import AsyncRedisStore   # or AsyncPostgresStore, or the default in-memory store
+
+guard = AsyncGuard(budgets={"per_day": 500}, rate={"per_minute": 10})
+send = guard.wrap(async_provider_send)      # wraps an async function
+decision = await guard.check(email)          # require_for may be async here
+```
+
+## Without wrap
+
+```python
+decision = guard.check(email)
+if decision.outcome == "allow":
+    try:
+        provider.send(email)
+    except Exception:
+        guard.release(decision)   # give back the reservation
+        raise
+    guard.record(email)           # feeds loop detection and new-recipient memory
+```
+
+`decision.reservation.to_dict()` is plain JSON, so a decision can be released from a different process.
+
+## Conformance
+
+Every port of agent-email-guard (Node, Python, PHP, Go) passes the same 45 conformance cases in [`../spec/vectors`](../spec/vectors). They pin each reason token, each sentence byte for byte, and each evidence field. The specification is [`../spec/SPEC.md`](../spec/SPEC.md).
+
+## License
+
+MIT. Copyright AgentiSend.

agent_email_guard-0.1.0/README.md

@@ -0,0 +1,169 @@
+# agent-email-guard
+
+Blast-radius control for agents that send email. It caps how much an agent can send and to whom, stops loops, holds chosen sends for a person, and gives you one call that stops everything. It works in front of any provider: AgentiSend, Resend, Amazon SES, SMTP, or your own function.
+
+It limits volume, repetition and recipients. It does not read intent or detect prompt injection; an agent tricked into sending one bad email within its limits still sends it.
+
+```bash
+pip install agent-email-guard
+```
+
+Python 3.9 or newer. No runtime dependencies. Redis and Postgres stores are optional extras.
+
+## Twelve lines
+
+```python
+from agent_email_guard import ApprovalRequired, Guard, GuardRefused
+
+guard = Guard(
+    budgets={"per_hour": 50, "per_day": 500},
+    rate={"per_minute": 10},
+    suppress=["@competitor.example"],
+)
+send = guard.wrap(provider.send)  # any function that takes one email dict
+
+try:
+    send({"to": "customer@example.com", "subject": "Your receipt", "text": "Thanks."})
+except (GuardRefused, ApprovalRequired) as stop:
+    print(stop.decision.reason, stop.decision.message)
+```
+
+`wrap()` keeps the function's signature. Each call is checked, sent, and recorded. If the provider raises, the reservation is given back and the provider's error reaches you unchanged.
+
+## What it decides
+
+Every check returns a `Decision` with four fields. `outcome` is `allow`, `hold_for_approval` or `refuse`. `reason` is a stable token. `message` is one sentence a person can read. `evidence` holds the numbers behind it:
+
+```python
+>>> guard.check({"to": "ops@example.com", "subject": "Disk at 91%", "text": "db-1"})
+Decision(outcome='refuse', reason='loop_repetition_detected',
+         message='Blocked: 3 near-identical emails already went to ops@example.com within 60 minutes, which matches a retry or script loop; review the agent before sending more.',
+         evidence={'matching_sends_in_window': 3, 'repetition_threshold': 3, 'window_ms': 3600000, ...})
+```
+
+Checks run in this order and stop at the first block:
+
+| # | Check | Outcome | Reason |
+|---|---|---|---|
+| 1 | Kill switch | refuse | `kill_switch_active` |
+| 2 | Suppression list | refuse | `recipient_suppressed` |
+| 3 | Loop detection | refuse | `loop_repetition_detected`, `recipient_entropy_collapse` |
+| 4 | Approval rules | hold | `recipient_requires_approval` |
+| 5 | Rate ceiling (sliding minute) | refuse | `rate_ceiling_exceeded` |
+| 6 | Budgets (UTC hour, day, month) | refuse | `agent_budget_exceeded` |
+| 7 | | allow | `ok` |
+
+Steps 1 to 4 reserve nothing. Steps 5 and 6 reserve atomically: 200 concurrent checks against a budget of 50 allow exactly 50 (the test suite runs this with threads and with asyncio).
+
+**Loop detection** uses two signals. The first is repetition: the agent has already sent 3 emails to the same To line within 60 minutes, with subject and body at least 85% similar (trigram Jaccard). The second is recipient collapse: across 20 or more recent sends, the effective number of recipients has dropped below 3. A collapsed window holds only a send to one of the inboxes it collapsed on. A sign-in code to a new user still goes out. Both signals and all five thresholds are configurable (`LOOP_DEFAULTS`). `loop={"mode": "repetition_only"}` turns off the collapse signal, and `loop=False` turns off both.
+
+**Approvals.** `approval={"recipients": ["@bigcustomer.com"]}` holds any send to that domain. `approval={"new_recipients": True}` holds a send to any address this key has never sent to. `approval={"require_for": fn}` holds a send whenever your function returns something truthy. Keep held sends wherever you like, then call `stop.approve()` once a person says yes. Every other check runs again before the email goes out.
+
+**Kill switch.** `guard.kill_switch.pause("looping on one inbox", by="ops")` stops every send through this guard, for every key, until someone calls `guard.kill_switch.resume("ops")`. There is no timer. A paused guard is still paused a year later.
+
+**Keys.** A send can name the agent it belongs to with `"key": "billing-agent"`. Each key gets its own budget, rate window, loop window and seen-recipient memory.
+
+## Policy file
+
+Keep the limits in `agent-email-guard.json` next to your code instead of inside it. The same file configures the Node, PHP and Go ports. An unknown key or a wrong type rejects the whole file with a sentence naming the key.
+
+```json
+{
+  "version": 1,
+  "key": "support-agent",
+  "budgets": {"per_hour": 50, "per_day": 500},
+  "rate": {"per_minute": 10},
+  "approval": {"new_recipients": true, "recipients": ["@bigcustomer.com"]},
+  "suppress": ["@competitor.example"]
+}
+```
+
+```python
+guard = Guard.from_policy()                       # reads ./agent-email-guard.json
+guard = Guard.from_policy("config/agent-email-guard.json", require_for=my_rule, store=store)
+```
+
+`require_for` is code, so it is passed in, never read from the file. Keyword arguments override the file.
+
+## Advisory here, enforced at AgentiSend
+
+This library runs inside the agent's own process. That makes it advisory. An agent that edits its own code, skips `check()`, or starts a second process with a fresh in-memory store can get around it. For many teams that is enough: the failure it catches is the agent stuck in a retry loop, not an agent fighting its operator.
+
+When you need limits the agent cannot remove, AgentiSend enforces the same rules at its API, on the API key itself. The rules are budget, per-minute ceiling, loop detection, approval queue and kill switch. Every process using that key shares them, and a paused key cannot resume itself: only a person signed in to the console can.
+
+```python
+from agent_email_guard.agentisend import AgentiSendGuard
+
+hosted = AgentiSendGuard(key_id="your-api-key-id")   # reads AGENTISEND_API_KEY
+hosted.apply_limits(budgets={"per_day": 500}, rate={"per_minute": 10})
+hosted.check(email)        # POST /emails/preflight: runs every gate, sends nothing
+hosted.send(email)         # POST /emails: raises GuardRefused / ApprovalRequired like the local guard
+hosted.kill_switch.pause("looping")
+hosted.approvals.list()    # held sends waiting for a person
+```
+
+A key can lower its own limits. Raising a limit is a person's decision, made in the console.
+
+## Integrations
+
+Each one is a runnable file in [`examples/`](examples/). The test suite runs every example against a stub.
+
+- **AgentiSend** ([`agentisend_sdk.py`](examples/agentisend_sdk.py)): `guard.wrap(AgentiSend().send_email)`, with the hosted adapter above for enforcement.
+- **Resend** ([`resend_sdk.py`](examples/resend_sdk.py)): `guard.wrap(resend.Emails.send)`.
+- **Amazon SES** ([`boto3_ses.py`](examples/boto3_ses.py)): `guard.wrap(ses.send_email, extract=...)`, which maps SES's keyword arguments to a send.
+- **SMTP** ([`smtp_stdlib.py`](examples/smtp_stdlib.py)): `smtplib` and `email.message`, standard library only.
+- **LangChain and the OpenAI Agents SDK** ([`agent_tool.py`](examples/agent_tool.py)): a `send_email` tool that returns the guard's sentence instead of raising. The model reads why a send was refused and does not retry in a loop.
+
+## Sharing limits across processes
+
+The in-memory store counts for one process. To share budgets, the rate window, the loop log and the kill switch across processes, use one of these:
+
+```python
+# pip install "agent-email-guard[redis]"
+import redis
+from agent_email_guard.stores.redis import RedisStore
+guard = Guard(budgets={"per_day": 500}, store=RedisStore(redis.Redis.from_url("redis://localhost:6379/0")))
+
+# pip install "agent-email-guard[postgres]"
+import psycopg
+from agent_email_guard.stores.postgres import PostgresStore
+store = PostgresStore(psycopg.connect("postgresql://localhost/app", autocommit=True))
+store.setup()  # creates four agent_email_guard_* tables if missing
+guard = Guard(budgets={"per_day": 500}, store=store)
+```
+
+Redis runs every check-and-reserve as one Lua script. Postgres uses one conditional upsert per counter, plus an advisory lock around the rate window. Store key names are shared with the Node, PHP and Go ports of agent-email-guard, so agents written in different languages can share one budget.
+
+## asyncio
+
+```python
+from agent_email_guard import AsyncGuard
+from agent_email_guard.stores.redis import AsyncRedisStore   # or AsyncPostgresStore, or the default in-memory store
+
+guard = AsyncGuard(budgets={"per_day": 500}, rate={"per_minute": 10})
+send = guard.wrap(async_provider_send)      # wraps an async function
+decision = await guard.check(email)          # require_for may be async here
+```
+
+## Without wrap
+
+```python
+decision = guard.check(email)
+if decision.outcome == "allow":
+    try:
+        provider.send(email)
+    except Exception:
+        guard.release(decision)   # give back the reservation
+        raise
+    guard.record(email)           # feeds loop detection and new-recipient memory
+```
+
+`decision.reservation.to_dict()` is plain JSON, so a decision can be released from a different process.
+
+## Conformance
+
+Every port of agent-email-guard (Node, Python, PHP, Go) passes the same 45 conformance cases in [`../spec/vectors`](../spec/vectors). They pin each reason token, each sentence byte for byte, and each evidence field. The specification is [`../spec/SPEC.md`](../spec/SPEC.md).
+
+## License
+
+MIT. Copyright AgentiSend.

agent_email_guard-0.1.0/examples/agent_tool.py

@@ -0,0 +1,57 @@
+"""A send-email tool for an LLM agent, guarded (LangChain or the OpenAI Agents SDK).
+
+The tool returns the guard's sentence instead of raising, so the model reads
+why a send was refused or held and can tell the user, rather than retrying
+in a loop. Register the same function with either framework:
+
+    pip install agent-email-guard langchain-core          # LangChain
+    pip install agent-email-guard openai-agents           # OpenAI Agents SDK
+"""
+
+from agent_email_guard import ApprovalRequired, Guard, GuardRefused
+
+guard = Guard(
+    budgets={"per_hour": 20, "per_day": 100},
+    rate={"per_minute": 5},
+    approval={"new_recipients": True},
+)
+
+#: Held sends, keyed by the recipient, for a person to approve later.
+held = {}
+
+
+def make_tool(provider_send, guard=guard):
+    guarded = guard.wrap(provider_send)
+
+    def send_email(to: str, subject: str, body: str) -> str:
+        """Send one email. Returns what happened, in a sentence."""
+        try:
+            result = guarded({"to": to, "subject": subject, "text": body})
+            return f"Sent ({result})."
+        except GuardRefused as stop:
+            return f"Not sent: {stop.decision.message}"
+        except ApprovalRequired as wait:
+            held[to] = wait
+            return f"Waiting for approval: {wait.decision.message}"
+
+    return send_email
+
+
+def as_langchain_tool(fn):
+    from langchain_core.tools import StructuredTool
+
+    return StructuredTool.from_function(fn, name="send_email", description=fn.__doc__)
+
+
+def as_openai_agents_tool(fn):
+    from agents import function_tool
+
+    return function_tool(fn)
+
+
+if __name__ == "__main__":
+    from agentisend import AgentiSend
+
+    client = AgentiSend()
+    tool_fn = make_tool(lambda p: client.send_email({"from": "agent@acme.dev", **p})["id"])
+    print(tool_fn("someone@example.com", "Hello", "First message."))

agent_email_guard-0.1.0/examples/agentisend_sdk.py

@@ -0,0 +1,30 @@
+"""agent-email-guard in front of the AgentiSend Python SDK (pip install agentisend agent-email-guard).
+
+Two layers: the local guard stops a runaway agent before a request leaves the
+process, and AgentiSend enforces the key's own limits at the API, where the
+agent cannot remove them. Run: AGENTISEND_API_KEY=... python agentisend_sdk.py
+"""
+
+from agent_email_guard import ApprovalRequired, Guard, GuardRefused
+
+
+def build_send(client, guard=None):
+    guard = guard or Guard(budgets={"per_hour": 50, "per_day": 500}, rate={"per_minute": 10})
+    return guard.wrap(client.send_email)
+
+
+def main():
+    from agentisend import AgentiSend
+
+    send = build_send(AgentiSend())  # reads AGENTISEND_API_KEY
+    try:
+        result = send({"from": "Acme <billing@acme.dev>", "to": "customer@example.com", "subject": "Your receipt", "text": "Thanks for your order."})
+        print("sent", result["id"])
+    except GuardRefused as stop:
+        print("refused:", stop.decision.reason, "-", stop.decision.message)
+    except ApprovalRequired as held:
+        print("held for a person:", held.decision.message)
+
+
+if __name__ == "__main__":
+    main()

agent_email_guard-0.1.0/examples/boto3_ses.py

@@ -0,0 +1,43 @@
+"""agent-email-guard in front of Amazon SES via boto3 (pip install boto3 agent-email-guard).
+
+SES's send_email takes keyword arguments in its own shape, so ``extract``
+maps them to the guard's send. Run with AWS credentials configured.
+"""
+
+from agent_email_guard import Guard, GuardRefused
+
+
+def ses_to_send(**kwargs):
+    dest = kwargs.get("Destination", {})
+    body = kwargs.get("Message", {}).get("Body", {})
+    return {
+        "to": dest.get("ToAddresses", []),
+        "cc": dest.get("CcAddresses", []),
+        "bcc": dest.get("BccAddresses", []),
+        "subject": kwargs.get("Message", {}).get("Subject", {}).get("Data", ""),
+        "text": body.get("Text", {}).get("Data"),
+        "html": body.get("Html", {}).get("Data"),
+    }
+
+
+def build_send(ses_client, guard=None):
+    guard = guard or Guard(budgets={"per_day": 1000}, rate={"per_minute": 14})
+    return guard.wrap(ses_client.send_email, extract=ses_to_send)
+
+
+def main():
+    import boto3
+
+    send = build_send(boto3.client("ses", region_name="us-east-1"))
+    try:
+        send(
+            Source="billing@acme.dev",
+            Destination={"ToAddresses": ["customer@example.com"]},
+            Message={"Subject": {"Data": "Your invoice"}, "Body": {"Text": {"Data": "Invoice attached."}}},
+        )
+    except GuardRefused as stop:
+        print(stop.decision.message)
+
+
+if __name__ == "__main__":
+    main()

agent_email_guard-0.1.0/examples/resend_sdk.py

@@ -0,0 +1,29 @@
+"""agent-email-guard in front of the Resend Python SDK (pip install resend agent-email-guard).
+
+resend.Emails.send(params) keeps its signature; the guard checks first and
+records only what Resend accepted. Run: RESEND_API_KEY=... python resend_sdk.py
+"""
+
+from agent_email_guard import Guard, GuardRefused
+
+
+def build_send(emails_api, guard=None):
+    guard = guard or Guard(budgets={"per_day": 500}, rate={"per_minute": 10}, approval={"recipients": ["@bigcustomer.com"]})
+    return guard.wrap(emails_api.send)
+
+
+def main():
+    import os
+
+    import resend
+
+    resend.api_key = os.environ["RESEND_API_KEY"]
+    send = build_send(resend.Emails)
+    try:
+        print(send({"from": "Acme <onboarding@acme.dev>", "to": ["new-user@example.com"], "subject": "Welcome", "html": "<p>Hi!</p>"}))
+    except GuardRefused as stop:
+        print(stop.decision.reason, stop.decision.message)
+
+
+if __name__ == "__main__":
+    main()

agent_email_guard-0.1.0/examples/smtp_stdlib.py

@@ -0,0 +1,49 @@
+"""agent-email-guard in front of plain SMTP with the standard library (pip install agent-email-guard).
+
+Works with any SMTP server. Run: SMTP_HOST=... SMTP_USER=... SMTP_PASSWORD=... python smtp_stdlib.py
+"""
+
+import os
+import smtplib
+from email.message import EmailMessage
+
+from agent_email_guard import Guard, GuardRefused
+
+
+def message_to_send(msg):
+    return {
+        "to": msg.get_all("To", []),
+        "cc": msg.get_all("Cc", []),
+        "subject": msg.get("Subject", ""),
+        "text": msg.get_content() if not msg.is_multipart() else "",
+    }
+
+
+def build_send(smtp_factory, guard=None):
+    guard = guard or Guard(budgets={"per_hour": 100}, rate={"per_minute": 20})
+
+    def deliver(msg):
+        with smtp_factory() as smtp:
+            smtp.send_message(msg)
+
+    return guard.wrap(deliver, extract=message_to_send)
+
+
+def main():
+    def factory():
+        smtp = smtplib.SMTP(os.environ["SMTP_HOST"], int(os.environ.get("SMTP_PORT", "587")))
+        smtp.starttls()
+        smtp.login(os.environ["SMTP_USER"], os.environ["SMTP_PASSWORD"])
+        return smtp
+
+    msg = EmailMessage()
+    msg["From"], msg["To"], msg["Subject"] = "alerts@acme.dev", "oncall@acme.dev", "Disk at 91%"
+    msg.set_content("db-1 crossed 90% disk.")
+    try:
+        build_send(factory)(msg)
+    except GuardRefused as stop:
+        print(stop.decision.message)
+
+
+if __name__ == "__main__":
+    main()

agent_email_guard-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-email-guard"
+version = "0.1.0"
+description = "Blast-radius control for agents that send email: budgets, a rate ceiling, loop detection, approval holds and a kill switch, in front of any provider."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AgentiSend", email = "hello@agentisend.com" }]
+keywords = ["ai-agents", "email", "guardrails", "rate-limit", "mcp", "resend-alternative", "budget", "loop-detection", "kill-switch"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=4.2"]
+postgres = ["psycopg>=3.1"]
+dev = ["pytest>=7", "fakeredis[lua]>=2.20"]
+
+[project.urls]
+Homepage = "https://agentisend.com"
+Source = "https://github.com/agentisend/agent-email-guard"
+Issues = "https://github.com/agentisend/agent-email-guard/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_email_guard"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agent_email_guard", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]