{"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,"last_verified":"2026-05-22T21:45:01.425Z","next_check":"2026-07-12T00:00:00.000Z","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,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.0","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,"install_checks":{"last_tested":"2026-05-22","tag":null,"tag_description":null,"installed_version":"0.5.0","pypi_latest":"0.5.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.56,"mem_mb":14.2,"disk_size":"37.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.56,"mem_mb":14.2,"disk_size":"37.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.8,"import_time_s":0.39,"mem_mb":14.2,"disk_size":"37M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.8,"import_time_s":0.39,"mem_mb":14.2,"disk_size":"37M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.74,"mem_mb":14.8,"disk_size":"41.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.73,"mem_mb":14.8,"disk_size":"41.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4,"import_time_s":0.68,"mem_mb":14.8,"disk_size":"41M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.2,"import_time_s":0.67,"mem_mb":14.8,"disk_size":"41M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.86,"mem_mb":14.7,"disk_size":"32.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.9,"mem_mb":14.7,"disk_size":"32.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.5,"import_time_s":0.88,"mem_mb":14.7,"disk_size":"32M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.5,"import_time_s":0.89,"mem_mb":14.7,"disk_size":"32M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.85,"mem_mb":15.4,"disk_size":"32.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.88,"mem_mb":15.4,"disk_size":"32.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.6,"import_time_s":0.81,"mem_mb":15.4,"disk_size":"32M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.6,"import_time_s":0.8,"mem_mb":15.4,"disk_size":"32M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.5,"mem_mb":13.2,"disk_size":"36.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.51,"mem_mb":13.2,"disk_size":"37.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.4,"import_time_s":0.5,"mem_mb":13.2,"disk_size":"37M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"agentmail","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.5,"import_time_s":0.48,"mem_mb":13.2,"disk_size":"37M"}]},"_links":{"self":"https://checklist.day/api/registry/agentmail","v1":"https://checklist.day/v1/registry/agentmail","v1_install":"https://checklist.day/v1/registry/agentmail/install","v1_imports":"https://checklist.day/v1/registry/agentmail/imports","v1_compatibility":"https://checklist.day/v1/registry/agentmail/compatibility","v1_quickstart":"https://checklist.day/v1/registry/agentmail/quickstart","docs":"https://checklist.day/docs"}}