Quickstart

$
pip install agentmail

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="am_...")
4
inbox = client.inboxes.create()
5
client.inboxes.messages.send(inbox.inbox_id, to="user@example.com", subject="Hello", text="Hello from my agent!")

1
"""
2
AgentMail Python Quickstart — copy into Cursor/Claude for instant setup.
3
4
Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5
6
API reference:
7
- inboxes.create(username?, domain?, display_name?, client_id?) — client_id for idempotent retries
8
- messages.send(inbox_id, to, subject, text, html?, cc?, bcc?, reply_to?, attachments?)
9
- messages.list(inbox_id, limit?, page_token?, labels?) — receive emails; use extracted_text/extracted_html for reply content
10
11
Errors: SDK raises on 4xx/5xx. Inspect error.body.message or str(e).
12
Rate limit: 429 with Retry-After header. Implement exponential backoff for retries.
13
Idempotency: Pass client_id to inboxes.create() to safely retry without duplicates.
14
"""
15
import os
16
from dotenv import load_dotenv
17
from agentmail import AgentMail
18
19
load_dotenv()
20
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
21
22
# Create inbox (client_id enables safe retries)
23
inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
24
25
# Send email
26
try:
27
    client.inboxes.messages.send(
28
        inbox.inbox_id,
29
        to="recipient@example.com",
30
        subject="Hello from AgentMail",
31
        text="Plain text body",
32
        html="<p>HTML body</p>",
33
    )
34
except Exception as e:
35
    # Handle validation, not found, rate limit (429), etc.
36
    print(f"Send failed: {e}")
37
    raise
38
39
# Receive messages
40
for msg in client.inboxes.messages.list(inbox.inbox_id, limit=10).messages:
41
    print(msg.subject, msg.extracted_text or msg.text)