Agent Onboarding

Fresh 🌱

Resources for AI coding assistants, MCP servers, skills, and agent-friendly documentation.

Everything you need to onboard your AI agent to AgentMail — the email platform built for AI agents.

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.

from agentmail import AgentMail

client = AgentMail()
response = client.agent.sign_up(human_email="you@example.com", username="my-agent")
# response.api_key  -> store this securely
# response.inbox_id -> my-agent@agentmail.to

import { AgentMailClient } from "agentmail";

const client = new AgentMailClient();
const response = await client.agent.signUp({ humanEmail: "you@example.com", username: "my-agent" });
// response.apiKey  -> store this securely
// response.inboxId -> my-agent@agentmail.to

agentmail agent sign-up --human-email you@example.com --username my-agent

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

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

const authedClient = new AgentMailClient({ apiKey: response.apiKey });
await authedClient.agent.verify({ otpCode: "123456" });

agentmail agent verify --otp-code 123456

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

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

AgentMail's free tier includes 3 inboxes and 3,000 emails/month. Your agent can start building immediately.

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.):

{
  "mcpServers": {
    "AgentMail": {
      "command": "npx",
      "args": ["-y", "agentmail-mcp"],
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

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

{
  "mcpServers": {
    "AgentMail": {
      "command": "npx",
      "args": ["-y", "agentmail-mcp", "--tools", "get_message,send_message,reply_to_message"],
      "env": {
        "AGENTMAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Available MCP Tools

Tool	Description
create_inbox	Create a new email inbox for an agent
list_inboxes	List all inboxes in your account
get_inbox	Get details of a specific inbox
delete_inbox	Delete an inbox
send_message	Send an email from an agent inbox
reply_to_message	Reply to an email in a thread
forward_message	Forward an email
update_message	Update message labels or status
create_draft	Create a draft email (optionally scheduled via send_at)
list_drafts	List drafts in an inbox (filter by labels like scheduled)
get_draft	Get a draft by ID with content and scheduled send time
update_draft	Update a draft; use send_at to reschedule
send_draft	Send a draft immediately (draft is converted to a sent message)
delete_draft	Delete a draft; also cancels a scheduled send
list_threads	List email threads in an inbox
get_thread	Get a full email thread with messages
get_attachment	Download an email attachment

View the source code, contribute, or report issues.

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"

View the skill source and full documentation.

Quick start for agents

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

from agentmail import AgentMail

# sign up (no API key needed)
client = AgentMail()
response = client.agent.sign_up(human_email="you@example.com", username="my-agent")

# after verifying with the OTP sent to your email:
client = AgentMail(api_key=response.api_key)
client.agent.verify(otp_code="123456")

# create an inbox and send an email
inbox = client.inboxes.create(display_name="My AI Agent")
print(f"Agent email: {inbox.inbox_id}")

client.inboxes.messages.send(
    inbox.inbox_id,
    to="user@example.com",
    subject="Hello from my AI agent",
    text="Hi! I'm an AI agent with my own email address."
)

import { AgentMailClient } from "agentmail";

// sign up (no API key needed)
const client = new AgentMailClient();
const response = await client.agent.signUp({ humanEmail: "you@example.com", username: "my-agent" });

// after verifying with the OTP sent to your email:
const authedClient = new AgentMailClient({ apiKey: response.apiKey });
await authedClient.agent.verify({ otpCode: "123456" });

// create an inbox and send an email
const inbox = await authedClient.inboxes.create({ displayName: "My AI Agent" });
console.log(`Agent email: ${inbox.inboxId}`);

await authedClient.inboxes.messages.send(inbox.inboxId, {
    to: "user@example.com",
    subject: "Hello from my AI agent",
    text: "Hi! I'm an AI agent with my own email address."
});

# sign up and verify
agentmail agent sign-up --human-email you@example.com --username my-agent
agentmail agent verify --otp-code 123456

# create an inbox
agentmail inboxes create --display-name "My AI Agent"

# send an email (replace <inbox_id> with the id from above)
agentmail inboxes:messages send \
  --inbox-id <inbox_id> \
  --to user@example.com \
  --subject "Hello from my AI agent" \
  --text "Hi! I'm an AI agent with my own email address."

Already have an API key? Skip the sign-up step and initialize the client directly with your key.

Receive and reply to emails

# List threads in the inbox
threads = client.inboxes.threads.list(inbox_id=inbox.inbox_id)

# Get the latest thread
thread = client.inboxes.threads.get(
    inbox_id=inbox.inbox_id,
    thread_id=threads.threads[0].thread_id
)

# Reply to the latest message
latest_message = thread.messages[-1]
client.inboxes.messages.reply(
    inbox_id=inbox.inbox_id,
    message_id=latest_message.message_id,
    to=[latest_message.from_],
    text="Thanks for your email! I'll look into this."
)

// List threads in the inbox
const threads = await authedClient.inboxes.threads.list(inbox.inboxId);

// Get the latest thread
const thread = await authedClient.inboxes.threads.get(
    inbox.inboxId,
    threads.threads[0].threadId
);

// Reply to the latest message
const latestMessage = thread.messages[thread.messages.length - 1];
await authedClient.inboxes.messages.reply(
    inbox.inboxId,
    latestMessage.messageId,
    { to: [latestMessage.from], text: "Thanks for your email! I'll look into this." }
);

AI Builder Integrations

AgentMail integrates with popular AI development platforms:

Build email agents on Replit with our template.

Add email to LiveKit voice agents.

Use AgentMail with OpenClaw agents.

Real-time email events without webhooks.

What Makes AgentMail Different?

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

Feature	AgentMail	Traditional Email APIs
Per-agent inboxes	✅ Create thousands via API	❌ Shared sending domains
Receive & parse emails	✅ Native with threads	⚠️ Limited or add-on
Threaded conversations	✅ First-class API support	❌ Not supported
Allowlists/blocklists	✅ Per-inbox controls	❌ Not available
Multi-tenant (Pods)	✅ Built-in isolation	❌ Build it yourself
WebSocket events	✅ Real-time streaming	❌ Webhooks only
IMAP/SMTP access	✅ Full protocol support	❌ API-only
Usage-based pricing	✅ Pay per email	❌ Per-inbox subscriptions

Next Steps

Step-by-step setup with environment variables and best practices.

Full interactive API documentation.

Build an agent that responds to emails in real-time.

Answers to common questions about email, deliverability, and agent patterns.