AGmail Documentation

Quickstart

Get your first agent inbox running in under a minute. No credit card, no verification, no waiting.

Option 1: OpenClaw Skill (recommended)

# Install the AGmail skill
$ openclaw skills install agmail

# Run your agent with email capabilities
$ openclaw run --skill agmail

# Your agent can now create inboxes, send/receive email,
# search messages, manage threads, and more.

Option 2: REST API

# Create an API key at console.agmail.ai
$ export AGMAIL_API_KEY="ag_live_..."

# Create an inbox
$ curl -X POST https://api.agmail.ai/v1/inboxes \
  -H "Authorization: Bearer $AGMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-agent"}'

# Response:
# {"id": "inb_8f3k2m", "email": "my-agent@agmail.ai", "created_at": "..."}

Option 3: Python / TypeScript SDK

from agmail import AGMail

client = AGMail()  # reads AGMAIL_API_KEY from env

# Create an inbox
inbox = client.inboxes.create(username="my-agent")
print(inbox.email)  # my-agent@agmail.ai

# Send an email
inbox.send(
  to="hello@acme.com",
  subject="Hello from my AI agent",
  body="This email was sent by an AI agent."
)

Authentication

All API requests require an API key. Pass it as a Bearer token in theAuthorizationheader.

Authorization: Bearer ag_live_your_key_here

API keys start with ag_live_ for production and ag_test_ for test environments. You can create API keys in the console.

When using an OpenClaw skill or Claude Code skill, authentication is handled automatically — the skill reads your API key from the AGMAIL_API_KEY environment variable.

Inboxes

An inbox is an email address owned by your agent. Each agent can have one or many inboxes. Creating an inbox is instant — no DNS setup, no verification.

Every inbox gets a unique email address. Inboxes on the free tier use the@agmail.ai domain. On paid plans you can bring your own domain.

Messages

Send and receive email messages through your agent's inboxes. Messages support HTML bodies, plain text, attachments, CC/BCC, and reply threading.

Sending

{
  "to": "recipient@example.com",
  "subject": "Hello from my agent",
  "body": "Plain text body",
  "html": "<p>HTML body</p>",
  "cc": ["cc@example.com"],
  "reply_to_message_id": "msg_optional"
}

Receiving

Inbound emails are delivered to your inbox automatically. You can poll for new messages via the API, or use webhooks / WebSockets for realtime delivery. Every inbound message goes through the outbound security guard to flag potential phishing or spam before it reaches your agent.

Threads

AGmail automatically groups related messages into threads using standard email headers (In-Reply-To, References). When your agent replies to a message, the reply is automatically threaded. You can list all messages in a thread, and your agent can follow multi-turn conversations naturally.

Custom Domains

On paid plans, you can bring your own domain so agents send from addresses likeagent@yourcompany.com. Domain setup involves adding DNS records (MX, SPF, DKIM) which AGmail provides automatically.

We handle DKIM signing, SPF alignment, and DMARC compliance so your agent's emails have maximum deliverability.

Webhooks & Realtime

Get notified instantly when your agent receives new email.

API Overview

The AGmail API is a RESTful JSON API. All endpoints are underhttps://api.agmail.ai/v1.

Inboxes API

Create an inbox

// Request body
{
  "username": "support-bot",       // required
  "domain": "agmail.ai",         // optional, defaults to agmail.ai
  "display_name": "Support Bot"   // optional
}

// Response 201
{
  "id": "inb_8f3k2m",
  "email": "support-bot@agmail.ai",
  "display_name": "Support Bot",
  "domain": "agmail.ai",
  "created_at": "2026-03-16T12:00:00Z"
}

Messages API

Send a message

{
  "to": "customer@example.com",
  "subject": "Re: Your order #4821",
  "body": "Your order has shipped. Tracking: 1Z999...",
  "reply_to_message_id": "msg_abc123"
}

// Response 201
{
  "id": "msg_2x9p4n",
  "thread_id": "thr_7k2m",
  "status": "sent",
  "guard_result": "pass"
}

The guard_result field shows whether the outbound security guard flagged anything. Possible values: pass,warn,block.

Domains API

Add and verify custom domains so your agents can send from your own email addresses.

// Request
{ "domain": "yourcompany.com" }

// Response — add these DNS records
{
  "id": "dom_9x2k",
  "domain": "yourcompany.com",
  "status": "pending_verification",
  "dns_records": [
    { "type": "MX", "host": "@", "value": "mail.agmail.ai" },
    { "type": "TXT", "host": "@", "value": "v=spf1 include:spf.agmail.ai ~all" },
    { "type": "CNAME", "host": "agmail._domainkey", "value": "...dkim.agmail.ai" }
  ]
}

Search API

Semantic search across all messages in your account. Find relevant conversations using natural language queries — not just keyword matching.

{
  "query": "customer asking about refund",
  "inbox_id": "inb_8f3k2m",  // optional, scope to inbox
  "limit": 10
}

OpenClaw Skill

The AGmail OpenClaw skill gives your agent 20 email tools out of the box. Install it once and your agent can create inboxes, send emails, read messages, search, manage domains, and more — all through natural language.

$ openclaw skills install agmail
✓ Installed agmail@1.0.0

# Available tools:
# agmail.create_inbox    — Create a new email inbox
# agmail.list_inboxes    — List all inboxes
# agmail.send_email      — Send an email message
# agmail.read_inbox      — Read messages from an inbox
# agmail.get_message     — Get a specific message
# agmail.reply_to_email  — Reply to a message in-thread
# agmail.search_emails   — Semantic search across messages
# agmail.get_thread      — Get full conversation thread
# agmail.add_domain      — Add a custom domain
# agmail.verify_domain   — Check domain DNS status
# ... and 10 more

Why skills over MCP? Skills are 10-32x cheaper in tokens than MCP because they use a lean, structured interface rather than serializing full JSON schemas on every call. For high-volume agent operations, this adds up fast.

Claude Code Skill

The AGmail Claude Code skill works identically to the OpenClaw skill. Install it in your Claude Code environment and your coding agent can sign up for services, extract 2FA codes, manage API accounts, and handle any email-based workflow autonomously.

Python SDK

$ pip install agmail

from agmail import AGMail

client = AGMail()

# Create inbox
inbox = client.inboxes.create(username="agent")

# Send email
msg = inbox.send(to="user@example.com", subject="Hi", body="Hello!")

# Read messages
messages = inbox.messages()
for m in messages:
  print(m.subject, m.from_address)

# Search
results = client.search("order refund request")

TypeScript SDK

$ npm install agmail

import { AGMail } from "agmail"

const client = new AGMail()

// Create inbox
const inbox = await client.inboxes.create({ username: "agent" })

// Send email
const msg = await inbox.send({
  to: "user@example.com",
  subject: "Hi",
  body: "Hello!"
})

// Read messages
const messages = await inbox.messages()

// Semantic search
const results = await client.search("order refund request")