{"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":"en","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-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}