AgentMail

AgentMail

AgentMail is an API-first email platform designed specifically for AI agents. Unlike traditional email providers (Gmail, Outlook), AgentMail provides programmatic inboxes, usage-based pricing, high-volume sending, and real-time webhooks.

Core Capabilities

Quick Start

1. Create an account at console.agentmail.to 2. Generate API key in the console dashboard 3. Install Python SDK: pip install agentmail python-dotenv 4. Set environment variable: AGENTMAIL_API_KEY=your_key_here

Basic Operations

Create an Inbox

from agentmail import AgentMail
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
Create inbox with custom username
inbox = client.inboxes.create(
    username="spike-assistant",  # Creates spike-assistant@agentmail.to
    client_id="unique-identifier"  # Ensures idempotency
)
print(f"Created: {inbox.inbox_id}")

Send Email

client.inboxes.messages.send(
    inbox_id="spike-assistant@agentmail.to",
    to="adam@example.com",
    subject="Task completed",
    text="The PDF rotation is finished. See attachment.",
    html="
The PDF rotation is finished. See attachment.
",
    attachments=[{
        "filename": "rotated.pdf",
        "content": base64.b64encode(file_data).decode()
    }]
)

List Inboxes

inboxes = client.inboxes.list(limit=10)
for inbox in inboxes.inboxes:
    print(f"{inbox.inbox_id} - {inbox.display_name}")

Advanced Features

Webhooks for Real-Time Processing

Set up webhooks to respond to incoming emails immediately:

# Register webhook endpoint
webhook = client.webhooks.create(
    url="https://your-domain.com/webhook",
    client_id="email-processor"
)

See WEBHOOKS.md for complete webhook setup guide including ngrok for local development.

Custom Domains

For branded email addresses (e.g., spike@yourdomain.com), upgrade to a paid plan and configure custom domains in the console.

Security: Webhook Allowlist (CRITICAL)

⚠️ Risk: Incoming email webhooks expose a prompt injection vector. Anyone can email your agent inbox with instructions like:

Solution: Use a Clawdbot webhook transform to allowlist trusted senders.

Implementation

1. Create allowlist filter at ~/.clawdbot/hooks/email-allowlist.ts:

const ALLOWLIST = [
  'adam@example.com',           // Your personal email
  'trusted-service@domain.com', // Any trusted services
];
export default function(payload: any) {
  const from = payload.message?.from?.[0]?.email;
  
  // Block if no sender or not in allowlist
  if (!from || !ALLOWLIST.includes(from.toLowerCase())) {
    console.log([email-filter] ❌ Blocked email from: ${from || 'unknown'});
    return null; // Drop the webhook
  }
  
  console.log([email-filter] ✅ Allowed email from: ${from});
  
  // Pass through to configured action
  return {
    action: 'wake',
    text: 📬 Email from ${from}:\n\n${payload.message.subject}\n\n${payload.message.text},
    deliver: true,
    channel: 'slack',  // or 'telegram', 'discord', etc.
    to: 'channel:YOUR_CHANNEL_ID'
  };
}

2. Update Clawdbot config (~/.clawdbot/clawdbot.json):

{
  "hooks": {
    "transformsDir": "~/.clawdbot/hooks",
    "mappings": [
      {
        "id": "agentmail",
        "match": { "path": "/agentmail" },
        "transform": { "module": "email-allowlist.ts" }
      }
    ]
  }
}

3. Restart gateway: clawdbot gateway restart

Alternative: Separate Session

If you want to review untrusted emails before acting:

{
  "hooks": {
    "mappings": [{
      "id": "agentmail",
      "sessionKey": "hook:email-review",
      "deliver": false  // Don't auto-deliver to main chat
    }]
  }
}

Then manually review via /sessions or a dedicated command.

Defense Layers

1. Allowlist (recommended): Only process known senders 2. Isolated session: Review before acting 3. Untrusted markers: Flag email content as untrusted input in prompts 4. Agent training: System prompts that treat email requests as suggestions, not commands

Scripts Available

References

When to Use AgentMail

1. Create an account at console.agentmail.to 2. Generate API key in the console dashboard 3. Install Python SDK: pip install agentmail python-dotenv 4. Set environment variable: AGENTMAIL_API_KEY=your_key_here