Get Started

Quickstart

Create your first inbox with the AgentMail API

For Agents

For agents that sign themselves up programmatically, no Console or dashboard needed. The agent registers itself using an email you provide and receives an API key in response. This flow is for first-time users only: human email addresses already signed up with AgentMail will not work here.

1

Sign up

The agent registers itself using the human email you provide and gets back an API key, inbox ID, and organization ID. An OTP is sent to that email.

$npm install -g agentmail-cli
$
$agentmail agent sign-up \
>  --human-email you@example.com \
>  --username my-agent

The sign-up endpoint is idempotent. Calling it again with the same email rotates the API key and resends the OTP if expired.

2

Verify with the OTP

Check the human’s email for a 6-digit OTP code and verify to unlock full permissions.

$export AGENTMAIL_API_KEY="am_..."  # from the sign-up response
$
$agentmail agent verify --otp-code 123456
3

Create an inbox and send an email

With the API key from sign-up, the agent can create inboxes and send mail on its own.

$# create an inbox
$agentmail inboxes create
$
$# send an email (replace <inbox_id> with the id from above)
$agentmail inboxes:messages send \
>  --inbox-id <inbox_id> \
>  --to recipient@example.com \
>  --subject "Hello" \
>  --text "Hello from my agent!"

For Humans

For developers who want to try AgentMail from the Console.

1

Sign up and get an API key

Go to the AgentMail Console, create an account, and generate an API key from the dashboard. API Key Creation Screenshot

2

Store your API key

Create a .env file in your project root and add your key:

$AGENTMAIL_API_KEY=am_...

We recommend using environment variables to keep your keys secure.

3

Install the SDK

Install the AgentMail SDK using your preferred package manager. We’ll also use a library to load the environment variable from the .env file.

$pip install agentmail python-dotenv
4

Create an inbox and send an email

Create a new file (e.g., quickstart.py or quickstart.ts) and add the following code. This script initializes the AgentMail client, creates a new inbox, and sends a test email.

1import os
2from dotenv import load_dotenv
3from agentmail import AgentMail
4
5# load the API key from the .env file
6load_dotenv()
7api_key = os.getenv("AGENTMAIL_API_KEY")
8
9# initialize the client
10client = AgentMail(api_key=api_key)
11
12# create an inbox
13print("Creating inbox...")
14inbox = client.inboxes.create() # domain is optional
15print("Inbox created successfully!")
16print(inbox)
17
18# send an email from the new inbox
19client.inboxes.messages.send(
20  inbox.inbox_id,
21  to="your-email@example.com",
22  subject="Hello from AgentMail!",
23  text="This is my first email sent with the AgentMail API.",
24)

The domain parameter is optional. If not provided, AgentMail will use the default @agentmail.to domain. If you would like a custom domain, please upgrade to a paid plan.

5

Run the code

Execute the script from your terminal.

$python quickstart.py

You should see the details of your newly created inbox printed to the console. Congratulations, you’ve successfully created your first AgentMail inbox!

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for a complete, working AgentMail integration. Each block includes setup, API reference, error handling, rate limiting, and idempotency guidance.

1"""
2AgentMail Python Quickstart — copy into Cursor/Claude for instant setup.
3
4Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5
6Agent 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
10API 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
15Errors: SDK raises on 4xx/5xx. Inspect error.body.message or str(e).
16Rate limit: 429 with Retry-After header. Implement exponential backoff for retries.
17Idempotency: Pass client_id to inboxes.create() to safely retry without duplicates.
18"""
19import os
20from dotenv import load_dotenv
21from agentmail import AgentMail
22
23load_dotenv()
24client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
25
26# create inbox (client_id enables safe retries)
27inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
28
29# send email
30try:
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    )
38except Exception as e:
39    # handle validation, not found, rate limit (429), etc.
40    print(f"Send failed: {e}")
41    raise
42
43# receive messages
44for msg in client.inboxes.messages.list(inbox.inbox_id, limit=10).messages:
45    print(msg.subject, msg.extracted_text or msg.text)

When receiving emails, messages include extracted_text and extracted_html for reply content without quoted history.

Next Steps

You’ve created an inbox and sent your first email. Now set up your agent to receive and respond to incoming messages:

Receive emails with WebSockets

The fastest way to receive emails. No public URL or ngrok needed.

Receive emails with webhooks

Get real-time HTTP notifications when emails arrive.

Sending & receiving guide

Build a complete conversational agent workflow.

API Reference

Explore the full API with interactive examples.

Looking for a different language? Email us at support@agentmail.cc and we’ll get you set up.