ClawAIMail

Email infrastructure for AI agents.

npm version License: MIT Documentation

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