Registry / communication / agentmail

agentmail

JSON →
library0.5.9pypypi✓ verified 21d ago

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
INSTALL
IMPORT
SIG · AGENTMAIL
A
agentmail
communicationpythonv0.5.9
Install
4.6s avg
Import
694ms
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.725s · 38.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 4.6s · import 0.663s · 38MB
38MB installed
● package 38MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AgentMail
from agentmail import AgentMail
AsyncAgentMail
from agentmail import AsyncAgentMail
Use this for asynchronous API interactions.
ApiError
from agentmail.core.api_error import ApiError
Base exception for API errors (4xx/5xx responses).

This quickstart demonstrates how to initialize the AgentMail client using an API key from environment variables, create a new inbox (or use an existing one), and send a basic email. It includes basic error handling and highlights the common use of `python-dotenv` for API key management.

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()
agentmail --version
Debug
Known issues
gotchaAPI 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')`.
affects: All versions
gotchaError 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.
affects: All versions
gotchaRate 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.
affects: All versions
gotchaIdempotent 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.
affects: All versions
gotchaAsynchronous 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'agentmail'
The 'agentmail' package is not installed in the Python environment.
fix
Install the package using 'pip install agentmail'.
ImportError: cannot import name 'AgentMail' from 'agentmail'
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'.
TypeError: __init__() missing 1 required positional argument: 'api_key'
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")'.
AttributeError: 'AgentMail' object has no attribute 'inboxes'
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'.
ValueError: Invalid API key provided
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.
Upgrade
Version history
0.5.9latest on PyPI · released Aug 3, 2026
Audit
Dependencies
python-dotenvoptionalCommonly used in quickstart examples for managing API keys from .env files, though not a strict dependency of the core library.
Agent activity
93 hits · last 30 days
node
80
Perplexity
1
OpenAI (training)
1
Resources
agentmail — pip install agentmail · libregistry