AgentMail Python SDK

Python client for AgentMail — open-source email server for AI agents.

Install

pip install agentmail-oss

Quick Start

from agentmail import AgentMail

client = AgentMail(api_key="your-key", base_url="http://localhost:3456")

# Create an inbox
inbox = client.inboxes.create(display_name="My Agent")
print(inbox.email)  # agent-xxx@inbox.agentmail.dev

# Send an email
email = client.emails.send(
    inbox.id,
    to="user@example.com",
    subject="Hello from my agent",
    body="This email was sent by an AI agent.",
)

# List emails
emails = client.emails.list(inbox.id)
for e in emails.emails:
    print(f"{e.direction}: {e.subject}")

# Thread memory (the key differentiator)
memory = client.threads.get_memory(inbox.id, email.thread_id)
print(memory.summary)

# Semantic search
results = client.threads.search_memory(
    inbox.id, email.thread_id, query="revenue report"
)

Async

from agentmail import AsyncAgentMail

async with AsyncAgentMail(api_key="your-key") as client:
    inbox = await client.inboxes.create(display_name="Async Agent")
    email = await client.emails.send(inbox.id, to="user@example.com", body="Hello!")

Attachments

# Upload
attachment = client.attachments.upload(
    file=open("report.pdf", "rb"),
    filename="report.pdf",
)

# Send with attachment
client.emails.send(
    inbox.id,
    to="user@example.com",
    subject="Report attached",
    body="See attached.",
    attachment_ids=[attachment.id],
)

# Download
data = client.attachments.download(attachment.id)
with open("downloaded.pdf", "wb") as f:
    f.write(data)

Authentication

# Option 1: Pass explicitly
client = AgentMail(api_key="your-key")

# Option 2: Environment variable
# export AGENTMAIL_API_KEY=your-key
client = AgentMail()

# Custom server URL
# export AGENTMAIL_BASE_URL=http://your-server:3456
client = AgentMail(base_url="http://your-server:3456")

API Reference

client.inboxes

client.emails

client.threads

client.attachments

client.webhooks

Error Handling

from agentmail import AgentMail, NotFoundError, AuthenticationError

try:
    client.inboxes.get("nonexistent-id")
except NotFoundError:
    print("Inbox not found")
except AuthenticationError:
    print("Invalid API key")

Requirements

• Python 3.9+
• AgentMail server running (self-hosted)

License

MIT