Skip to navigation
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.

import os
from dotenv import load_dotenv
from agentmail import AgentMail
# load the API key from the .env file
load_dotenv()
api_key = os.getenv("AGENTMAIL_API_KEY")
# initialize the client
client = AgentMail(api_key=api_key)
# create an inbox
print("Creating inbox...")
inbox = client.inboxes.create() # domain is optional
print("Inbox created successfully!")
print(inbox)
# send an email from the new inbox
client.inboxes.messages.send(
  inbox.inbox_id,
  to="your-email@example.com",
  subject="Hello from AgentMail!",
  text="This is my first email sent with the AgentMail API.",
)

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.

"""
AgentMail Python Quickstart — copy into Cursor/Claude for instant setup.
Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
Agent sign-up (no API key needed):
- agent.sign_up(human_email, username) — returns api_key, inbox_id, organization_id
- agent.verify(otp_code) — verify with OTP sent to human_email
API reference:
- inboxes.create(username?, domain?, display_name?, client_id?) — client_id for idempotent retries
- messages.send(inbox_id, to, subject, text, html?, cc?, bcc?, reply_to?, attachments?)
- messages.list(inbox_id, limit?, page_token?, labels?) — receive emails; use extracted_text/extracted_html for reply content
Errors: SDK raises on 4xx/5xx. Inspect error.body.message or str(e).
Rate limit: 429 with Retry-After header. Implement exponential backoff for retries.
Idempotency: Pass client_id to inboxes.create() to safely retry without duplicates.
"""
import os
from dotenv import load_dotenv
from agentmail import AgentMail
load_dotenv()
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
# create inbox (client_id enables safe retries)
inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
# send email
try:
    client.inboxes.messages.send(
        inbox.inbox_id,
        to="recipient@example.com",
        subject="Hello from AgentMail",
        text="Plain text body",
        html="<p>HTML body</p>",
    )
except Exception as e:
    # handle validation, not found, rate limit (429), etc.
    print(f"Send failed: {e}")
    raise
# receive messages
for msg in client.inboxes.messages.list(inbox.inbox_id, limit=10).messages:
    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.