AgentMail Python Library
raw JSON → 0.4.15 verified Fri May 15 auth: no python
The AgentMail Python library provides convenient access to the AgentMail APIs, an API-first email platform designed for AI agents. It allows programmatic creation and management of email inboxes, sending/receiving emails, and handling email-based workflows with webhooks and real-time events. The library is currently at version 0.4.15 and receives frequent updates, indicating an active development cadence.
pip install agentmail Common errors
error ModuleNotFoundError: No module named 'agentmail' ↓
cause The 'agentmail' package is not installed in the Python environment.
fix
Install the package using 'pip install agentmail'.
error ImportError: cannot import name 'AgentMail' from 'agentmail' ↓
cause The 'AgentMail' class is not found in the 'agentmail' module, possibly due to an outdated package version.
fix
Ensure the latest version of 'agentmail' is installed using 'pip install --upgrade agentmail'.
error TypeError: __init__() missing 1 required positional argument: 'api_key' ↓
cause The 'AgentMail' class constructor requires an 'api_key' argument that was not provided.
fix
Initialize the 'AgentMail' client with the 'api_key' parameter: 'client = AgentMail(api_key="YOUR_API_KEY")'.
error AttributeError: 'AgentMail' object has no attribute 'inboxes' ↓
cause The 'inboxes' attribute is missing, possibly due to an incorrect or incomplete installation of the 'agentmail' package.
fix
Reinstall the 'agentmail' package using 'pip install --force-reinstall agentmail'.
error ValueError: Invalid API key provided ↓
cause The API key supplied to the 'AgentMail' client is incorrect or has expired.
fix
Verify and use a valid API key obtained from the AgentMail console.
Warnings
gotcha API Key Management: AgentMail requires an `api_key` for authentication. Storing API keys directly in code is insecure. It's best practice to use environment variables (e.g., via `python-dotenv`) for secure access. ↓
fix Store `AGENTMAIL_API_KEY` in your environment or a `.env` file and load it using `os.environ.get('AGENTMAIL_API_KEY')`.
gotcha Error Handling: The SDK raises `agentmail.core.api_error.ApiError` for non-success (4xx or 5xx) API responses. Generic `Exception` catches might hide specific API issues. ↓
fix Implement specific `try...except ApiError as e:` blocks to inspect `e.status_code` and `e.body` for detailed error information.
gotcha Rate Limiting and Retries: While the SDK has built-in exponential backoff for 408, 429, and 5xx status codes, users should be aware that 429 (Too Many Requests) specifically indicates rate limits. ↓
fix Monitor for `ApiError` with `status_code == 429` and implement additional application-level retry logic with exponential backoff if the default SDK retries are insufficient for your use case.
gotcha Idempotent Operations: For operations that create resources (e.g., `client.inboxes.create()`), retrying without care can lead to duplicates. The `client_id` parameter helps prevent this. ↓
fix When creating resources that require idempotency, pass a unique `client_id` parameter to the API call. The AgentMail API will use this ID to ensure the operation is processed only once.
gotcha Asynchronous Client Usage: When using `AsyncAgentMail` with a custom HTTPX client, ensure you pass `httpx.AsyncClient()` and not `httpx.Client()` to the `httpx_client` parameter. ↓
fix If customizing the HTTP client for `AsyncAgentMail`, use `httpx.AsyncClient()` for `httpx_client` to maintain asynchronous behavior.
Install
pip install agentmail python-dotenv Install compatibility last tested: 2026-05-15 v0.5.0 (up to date)
python os / libc status wheel install import disk mem side effects
3.10 alpine (musl) wheel - 0.58s 37.6M 14.2M clean
3.10 alpine (musl) wheel - 0.53s 37.7M 14.2M clean
3.10 slim (glibc) wheel 4.6s 0.39s 37M 14.2M clean
3.10 slim (glibc) wheel 4.9s 0.39s 37M 14.2M clean
3.11 alpine (musl) wheel - 0.73s 41.2M 14.8M clean
3.11 alpine (musl) wheel - 0.73s 41.4M 14.8M clean
3.11 slim (glibc) wheel 4.1s 0.68s 41M 14.8M clean
3.11 slim (glibc) wheel 4.3s 0.67s 41M 14.8M clean
3.12 alpine (musl) wheel - 0.87s 32.6M 14.7M clean
3.12 alpine (musl) wheel - 0.89s 32.8M 14.7M clean
3.12 slim (glibc) wheel 3.5s 0.90s 32M 14.7M clean
3.12 slim (glibc) wheel 3.5s 0.89s 32M 14.7M clean
3.13 alpine (musl) wheel - 0.85s 32.3M 15.4M clean
3.13 alpine (musl) wheel - 0.86s 32.5M 15.4M clean
3.13 slim (glibc) wheel 3.6s 0.81s 32M 15.4M clean
3.13 slim (glibc) wheel 3.7s 0.80s 32M 15.4M clean
3.9 alpine (musl) wheel - 0.49s 36.9M 13.2M clean
3.9 alpine (musl) wheel - 0.50s 37.1M 13.2M clean
3.9 slim (glibc) wheel 5.4s 0.52s 37M 13.2M clean
3.9 slim (glibc) wheel 5.4s 0.46s 37M 13.2M clean
Imports
- AgentMail
from agentmail import AgentMail - AsyncAgentMail
from agentmail import AsyncAgentMail - ApiError
from agentmail.core.api_error import ApiError
Quickstart
import os
from agentmail import AgentMail
from dotenv import load_dotenv
load_dotenv() # Load environment variables from .env file
# Ensure AGENTMAIL_API_KEY is set in your .env file or environment variables
api_key = os.environ.get('AGENTMAIL_API_KEY', '')
if not api_key:
raise ValueError("AGENTMAIL_API_KEY environment variable not set.")
client = AgentMail(api_key=api_key)
def create_and_send_email():
try:
# Create an inbox (optional, often you'd use an existing one)
# For idempotency, you can pass a client_id:
# inbox = client.inboxes.create(username="my-agent-inbox", client_id="unique-id-123")
inbox = client.inboxes.create()
print(f"Inbox created: {inbox.inbox_id}")
# Send an email
send_response = client.inboxes.messages.send(
inbox_id=inbox.inbox_id,
to="recipient@example.com", # Replace with a real recipient email
subject="Hello from AgentMail!",
text="This is a test email sent from your AgentMail agent."
)
print(f"Email sent: Message ID {send_response.message_id}")
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
create_and_send_email()