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
| 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
Metadata
Release files for agentmail-oss 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentmail_oss-0.1.1.tar.gz | 13.8 kB | Without provenance | Details for agentmail_oss-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentmail_oss-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentmail_oss-0.1.1-py3-none-any.whl |
Total release size: 29.8 kB
Release files / agentmail_oss-0.1.1.tar.gz
| Download URL | agentmail_oss-0.1.1.tar.gz |
|---|---|
| Size | 13.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c40c1a8ead94003887715a7704290411b8cbbccb28f7a6186f1755097e7f2eec
|
|
BLAKE2b-256 checksum How to use checksums |
612cde41866a6d9478d84e39a9063501f60ca0e1872ed2a153aea67e2d2303e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / agentmail_oss-0.1.1-py3-none-any.whl
| Download URL | agentmail_oss-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a13ff475ba68a78a9ae84d85c4e3623321022c1e0c6b0d5acd45f977ab63b451
|
|
BLAKE2b-256 checksum How to use checksums |
9fb304a1cb86512be8a7ae92d7fc7669ceead815a42187ebf015f02e3c9c2602
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for agentmail-oss 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.