io.github.joansongjr/clawaimail

ClawAIMail

Email infrastructure for AI agents.

ClawAIMail gives AI agents their own email addresses and full programmatic control over sending, receiving, and managing email. Built for developers who need reliable email primitives in agentic workflows.

Features

• REST API -- Send, receive, search, and manage emails with a simple JSON API.
• MCP Server -- First-class Model Context Protocol server for Claude, Cursor, and other MCP-compatible clients.
• WebSocket Streaming -- Real-time email events pushed to your agent as they happen.
• Webhooks -- HTTP callbacks on incoming mail, delivery status, and other events.
• Custom Domains -- Bring your own domain or use a @clawaimail.com address.
• SDKs -- Official Node.js and Python SDKs for rapid integration.

Quick Start

Node.js

npm install clawaimail

const { ClawAIMail } = require("clawaimail");

const client = new ClawAIMail({ apiKey: process.env.CLAWAIMAIL_API_KEY });

// Create a mailbox for your agent
const mailbox = await client.mailboxes.create({
  name: "support-agent",
  domain: "clawaimail.com",
});

// Send an email
await client.emails.send({
  from: mailbox.address,
  to: "user@example.com",
  subject: "Hello from my AI agent",
  text: "This email was sent by an autonomous agent.",
});

// List incoming emails
const inbox = await client.emails.list({
  mailbox: mailbox.id,
  unread: true,
});

Python

pip install clawaimail

from clawaimail import ClawAIMail

client = ClawAIMail(api_key="your-api-key")

# Create a mailbox
mailbox = client.mailboxes.create(name="support-agent", domain="clawaimail.com")

# Send an email
client.emails.send(
    from_address=mailbox.address,
    to="user@example.com",
    subject="Hello from my AI agent",
    text="This email was sent by an autonomous agent.",
)

# List incoming emails
inbox = client.emails.list(mailbox=mailbox.id, unread=True)

MCP Server

ClawAIMail ships an MCP server so that Claude, Cursor, and other MCP-compatible clients can use email tools directly.

Claude Desktop

Add the following to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "clawaimail": {
      "command": "npx",
      "args": ["-y", "clawaimail-mcp"],
      "env": {
        "CLAWAIMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "clawaimail": {
      "command": "npx",
      "args": ["-y", "clawaimail-mcp"],
      "env": {
        "CLAWAIMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Once configured, the agent can call tools like send_email, read_inbox, search_emails, and create_mailbox without any additional code.

Self-Hosting

ClawAIMail can be self-hosted for full control over your email infrastructure.

# Clone the repository
git clone https://github.com/joansongjr/clawaimail.git
cd clawaimail

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your SMTP credentials, database URL, and API keys

# Run database migrations
npm run db:migrate

# Start the server
npm start

The server will be available at http://localhost:3000 by default. See the self-hosting docs for production deployment guides (Docker, Railway, Fly.io).

API Endpoints

Full API reference: clawaimail.com/docs/api

Pricing

Self-hosted deployments are free and unlimited. See clawaimail.com/pricing for details.

Links

• Documentation
• Node.js SDK
• Python SDK
• Website
• Status Page

License

MIT -- see LICENSE for details.