Agent Onboarding

If you’re developing with AI, AgentMail offers several resources to improve your experience.

Get an API key

Your agent can sign up programmatically using the Agent API. No console access needed.

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

A 6-digit OTP is sent to the provided email. Verify to unlock full permissions:

1
client = AgentMail(api_key=response.api_key)
2
client.agent.verify(otp_code="123456")

Alternatively, a human can create an account at console.agentmail.to and generate an API key from the dashboard.

AgentMail MCP Server

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. The AgentMail MCP server gives your AI agent tools to create inboxes, send emails, manage threads, and more.

Setup

Add this to your MCP client configuration (Claude Code, Cursor, Codex, etc.):

1
{
2
  "mcpServers": {
3
    "AgentMail": {
4
      "command": "npx",
5
      "args": ["-y", "agentmail-mcp"],
6
      "env": {
7
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
8
      }
9
    }
10
  }
11
}

You can selectively enable specific tools using the --tools argument:

1
{
2
  "mcpServers": {
3
    "AgentMail": {
4
      "command": "npx",
5
      "args": ["-y", "agentmail-mcp", "--tools", "get_message,send_message,reply_to_message"],
6
      "env": {
7
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
8
      }
9
    }
10
  }
11
}

Available MCP Tools

AgentMail Docs for Agents

You can give your agent current docs in three ways:

1. Full documentation index

   A structured index of every doc page with descriptions:

   https://docs.agentmail.to/llms.txt

2. Complete docs in one file

   Every doc page concatenated into a single file for full context:

   https://docs.agentmail.to/llms-full.txt

3. Markdown versions of any page

   Every doc page is available as Markdown. Append .md to any page URL:

   https://docs.agentmail.to/quickstart.md

AgentMail Skills

Skills give AI agents specialized knowledge for specific tasks. Install the AgentMail skill to give your coding assistant full email capabilities:

Claude Code

$
claude-code skills install agentmail-to/agentmail-skills/agentmail

Cursor

$
cursor skills install agentmail-to/agentmail-skills/agentmail

Codex

$
codex skills install agentmail-to/agentmail-skills/agentmail

Manual Installation

$
git clone https://github.com/agentmail-to/agentmail-skills.git ~/.skills/agentmail

Then set your API key:

$
export AGENTMAIL_API_KEY="your-api-key-here"

Quick start for agents

Sign up, create an inbox, and send your first email:

1
from agentmail import AgentMail
2
3
# sign up (no API key needed)
4
client = AgentMail()
5
response = client.agent.sign_up(human_email="you@example.com", username="my-agent")
6
7
# after verifying with the OTP sent to your email:
8
client = AgentMail(api_key=response.api_key)
9
client.agent.verify(otp_code="123456")
10
11
# create an inbox and send an email
12
inbox = client.inboxes.create(display_name="My AI Agent")
13
print(f"Agent email: {inbox.inbox_id}")
14
15
client.inboxes.messages.send(
16
    inbox.inbox_id,
17
    to="user@example.com",
18
    subject="Hello from my AI agent",
19
    text="Hi! I'm an AI agent with my own email address."
20
)

Receive and reply to emails

1
# List threads in the inbox
2
threads = client.inboxes.threads.list(inbox_id=inbox.inbox_id)
3
4
# Get the latest thread
5
thread = client.inboxes.threads.get(
6
    inbox_id=inbox.inbox_id,
7
    thread_id=threads.threads[0].thread_id
8
)
9
10
# Reply to the latest message
11
latest_message = thread.messages[-1]
12
client.inboxes.messages.reply(
13
    inbox_id=inbox.inbox_id,
14
    message_id=latest_message.message_id,
15
    to=[latest_message.from_],
16
    text="Thanks for your email! I'll look into this."
17
)

AI Builder Integrations

AgentMail integrates with popular AI development platforms:

What Makes AgentMail Different?

Unlike traditional email APIs that are built for one-way transactional email, AgentMail is built for two-way agent communication:

Next Steps