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.

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.

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

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

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

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

Documentation

• Full docs: mails.ai/docs
• Source: github.com/RolloutsAI/mails-api

License

MIT