Quickstart

$
pip install agentmail

1
from agentmail import AgentMail
2
3
client = AgentMail()
4
response = client.agent.sign_up(human_email="you@example.com", username="my-agent")
5
# response.api_key  -> store this securely
6
# response.inbox_id -> my-agent@agentmail.to

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