agentmail-oss 0.1.0

Python SDK for AgentMail — open-source email server for AI agents

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)  # [e-mail]

# Send an email
email = client.emails.send(
    inbox.id,
    to="[e-mail]",
    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="[e-mail]", 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="[e-mail]",
    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

Method	Description
.create(display_name?, metadata?)	Create inbox
.list()	List all inboxes
.get(inbox_id)	Get inbox with stats
.delete(inbox_id)	Delete inbox

client.emails

Method	Description
.send(inbox_id, to=, subject?, body?, html_body?, attachment_ids?)	Send email
.list(inbox_id, direction?, limit?, offset?)	List emails
.get(inbox_id, email_id)	Get email
.update(inbox_id, email_id, is_read?, is_archived?)	Update email
.delete(inbox_id, email_id)	Delete email

client.threads

Method	Description
.list(inbox_id)	List threads
.get(inbox_id, thread_id)	Get thread with messages
.reply(inbox_id, thread_id, to=, body?)	Reply to thread
.update(inbox_id, thread_id, is_archived?, labels?)	Update thread
.delete(inbox_id, thread_id)	Delete thread
.get_memory(inbox_id, thread_id)	Get thread memory for agent prompts
.search_memory(inbox_id, thread_id, query=)	Semantic search within thread
.refresh_memory(inbox_id, thread_id)	Refresh rolling summary

client.attachments

Method	Description
.upload(file=, filename?, content_type?)	Upload attachment (25MB max)
.download(attachment_id)	Download as bytes
.get_metadata(attachment_id)	Get metadata
.delete(attachment_id)	Delete attachment

client.webhooks

Method	Description
.create(url=, events?, secret?)	Register webhook
.list()	List webhooks
.delete(webhook_id)	Delete webhook

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