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

Method	Endpoint	Description
POST	/v1/emails/send	Send an email
GET	/v1/emails	List emails for a mailbox
GET	/v1/emails/:id	Get a single email by ID
DELETE	/v1/emails/:id	Delete an email
POST	/v1/mailboxes	Create a new mailbox
GET	/v1/mailboxes	List all mailboxes
DELETE	/v1/mailboxes/:id	Delete a mailbox
POST	/v1/webhooks	Register a webhook
GET	/v1/webhooks	List registered webhooks
DELETE	/v1/webhooks/:id	Remove a webhook
GET	/v1/domains	List verified domains
POST	/v1/domains/verify	Verify a custom domain
GET	/v1/ws	WebSocket connection for real-time events

Full API reference: clawaimail.com/docs/api

Pricing

	Free	Starter	Pro	Business
Price	$0/mo	$5/mo	$29/mo	$99/mo
Emails/month	100	5,000	50,000	500,000
Mailboxes	1	10	100	Unlimited
Custom domains	--	1	5	Unlimited
Webhooks	1	5	25	Unlimited
WebSocket	--	Yes	Yes	Yes
Support	Community	Email	Priority	Dedicated

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.