AgentMail Python SDK

The official Python client library for AgentMail — the email inbox API built for AI agents.

Installation

pip install agentmail

With async support:

pip install agentmail[async]

Quickstart

from agentmail import AgentMail

client = AgentMail(api_key="am_live_...")

# Create an inbox for your agent
inbox = client.inboxes.create(username="my-agent")

# Send an email
message = client.send.send(
    inbox_id=inbox.id,
    to=["user@example.com"],
    subject="Your OTP Code",
    body_text="Your verification code is 847291.",
)

# Wait for a reply with a matching OTP
reply = client.inboxes.wait_for_message(
    inbox.id,
    timeout=60,
    from_addr="user@example.com",
)
print(f"OTP received: {reply.extracted_otp}")

Key Features

• Auto-retry on rate limits (429) and server errors (5xx) — exponential backoff, max 3 attempts
• Pagination via cursor — client.inboxes.list() returns an iterator
• Typed models — all API objects are Pydantic v2 models with full type hints
• py.typed marker — compatible with mypy and pyright
• Context manager — with AgentMail(api_key="...") as client:

Resource Namespaces

Error Handling

from agentmail import AgentMail, AgentMailError, RateLimitError, NotFoundError

try:
    inbox = client.inboxes.get("invalid-id")
except NotFoundError as e:
    print(f"Inbox not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited — retry after: {e.message}")
except AgentMailError as e:
    print(f"API error [{e.error_code}]: {e.message}")

Examples

OTP Verification Flow

from agentmail import AgentMail

client = AgentMail(api_key="am_live_...")

# Create agent inbox
inbox = client.inboxes.create(username="otp-bot")

# Wait for email containing OTP (blocks up to 60s)
message = client.inboxes.wait_for_message(
    inbox.id,
    timeout=60,
    subject="Your verification code",
)
otp = message.extracted_otp
print(f"OTP: {otp}")  # e.g. "482917"

Multi-Agent Inbox Provisioning

# Bulk create inboxes for a team of agents
agent_names = ["sales-agent", "support-agent", "billing-agent"]
for name in agent_names:
    inbox = client.inboxes.create(username=name, agent_name=name)
    print(f"Created: {inbox.address}")

Webhook Registration + Delivery Log

import os

# Register a webhook for all message events
webhook = client.webhooks.create(
    url="https://my-agent.example.com/webhook",
    events=["message.received", "message.sent"],
)

# Inspect recent webhook deliveries
deliveries = client.webhooks.delivery_log(webhook.id)
for d in deliveries:
    print(f"{d['event']}: {d['status_code']} at {d['createdAt']}")

Configuration

client = AgentMail(
    api_key="am_live_...",
    base_url="https://api.agentmail.to",  # optional, for testing
    timeout=30.0,                          # request timeout (default 30s)
    max_retries=3,                         # auto-retry attempts (default 3)
    debug=True,                            # log requests/responses
)

License

MIT © AgentMail Team