{"id":5103,"library":"agentmail","title":"AgentMail Python Library","description":"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.","status":"active","version":"0.4.15","language":"python","source_language":"en","source_url":"https://github.com/agentmail-to/agentmail-python","tags":["email","api","ai agents","automation","sdk","agentic"],"install":[{"cmd":"pip install agentmail","lang":"bash","label":"Install core library"},{"cmd":"pip install agentmail python-dotenv","lang":"bash","label":"Install with dotenv for API key management"}],"dependencies":[{"reason":"Commonly used in quickstart examples for managing API keys from .env files, though not a strict dependency of the core library.","package":"python-dotenv","optional":true}],"imports":[{"symbol":"AgentMail","correct":"from agentmail import AgentMail"},{"note":"Use this for asynchronous API interactions.","symbol":"AsyncAgentMail","correct":"from agentmail import AsyncAgentMail"},{"note":"Base exception for API errors (4xx/5xx responses).","symbol":"ApiError","correct":"from agentmail.core.api_error import ApiError"}],"quickstart":{"code":"import os\nfrom agentmail import AgentMail\nfrom dotenv import load_dotenv\n\nload_dotenv() # Load environment variables from .env file\n\n# Ensure AGENTMAIL_API_KEY is set in your .env file or environment variables\napi_key = os.environ.get('AGENTMAIL_API_KEY', '')\n\nif not api_key:\n    raise ValueError(\"AGENTMAIL_API_KEY environment variable not set.\")\n\nclient = AgentMail(api_key=api_key)\n\ndef create_and_send_email():\n    try:\n        # Create an inbox (optional, often you'd use an existing one)\n        # For idempotency, you can pass a client_id:\n        # inbox = client.inboxes.create(username=\"my-agent-inbox\", client_id=\"unique-id-123\")\n        inbox = client.inboxes.create()\n        print(f\"Inbox created: {inbox.inbox_id}\")\n\n        # Send an email\n        send_response = client.inboxes.messages.send(\n            inbox_id=inbox.inbox_id,\n            to=\"recipient@example.com\", # Replace with a real recipient email\n            subject=\"Hello from AgentMail!\",\n            text=\"This is a test email sent from your AgentMail agent.\"\n        )\n        print(f\"Email sent: Message ID {send_response.message_id}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    create_and_send_email()","lang":"python","description":"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."},"warnings":[{"fix":"Store `AGENTMAIL_API_KEY` in your environment or a `.env` file and load it using `os.environ.get('AGENTMAIL_API_KEY')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement specific `try...except ApiError as e:` blocks to inspect `e.status_code` and `e.body` for detailed error information.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If customizing the HTTP client for `AsyncAgentMail`, use `httpx.AsyncClient()` for `httpx_client` to maintain asynchronous behavior.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.4.15':55 'access':10 'activ':62 'agent':24,68,71 'agentmail':1,5,13 'ai':23,67 'allow':26 'api':14,17,66 'api-first':16 'autom':69 'base':40 'cadenc':64 'conveni':9 'creation':28 'current':52 'design':21 'develop':63 'email':19,32,35,39,65 'email-bas':38 'event':48 'first':18 'frequent':58 'handl':37 'inbox':33 'indic':60 'librari':3,7,50 'manag':30 'platform':20 'programmat':27 'provid':8 'python':2,6 'real':46 'real-tim':45 'receiv':57 'sdk':70 'sending/receiving':34 'time':47 'updat':59 'version':54 'webhook':43 'workflow':41","created_at":"2026-04-14T01:19:19.325142+00:00","updated_at":"2026-04-15T19:20:27.935534+00:00","problems":[{"fix":"Install the package using 'pip install agentmail'.","cause":"The 'agentmail' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'agentmail'"},{"fix":"Ensure the latest version of 'agentmail' is installed using 'pip install --upgrade agentmail'.","cause":"The 'AgentMail' class is not found in the 'agentmail' module, possibly due to an outdated package version.","error":"ImportError: cannot import name 'AgentMail' from 'agentmail'"},{"fix":"Initialize the 'AgentMail' client with the 'api_key' parameter: 'client = AgentMail(api_key=\"YOUR_API_KEY\")'.","cause":"The 'AgentMail' class constructor requires an 'api_key' argument that was not provided.","error":"TypeError: __init__() missing 1 required positional argument: 'api_key'"},{"fix":"Reinstall the 'agentmail' package using 'pip install --force-reinstall agentmail'.","cause":"The 'inboxes' attribute is missing, possibly due to an incorrect or incomplete installation of the 'agentmail' package.","error":"AttributeError: 'AgentMail' object has no attribute 'inboxes'"},{"fix":"Verify and use a valid API key obtained from the AgentMail console.","cause":"The API key supplied to the 'AgentMail' client is incorrect or has expired.","error":"ValueError: Invalid API key provided"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.9","cli_name":"agentmail","cli_version":"sh: 1: agentmail: not found","type":"library","homepage":"https://agentmail.to","github":"https://github.com/agentmail-to/agentmail-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/agentmail/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","llm-agents","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}