io.github.joansongjr/clawaimail
Email infrastructure for AI agents. Create inboxes, send/receive email, and search messages.
Ask AI about io.github.joansongjr/clawaimail
Powered by Claude · Grounded in docs
I know everything about io.github.joansongjr/clawaimail. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.comaddress. - 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 | Priority | Dedicated |
Self-hosted deployments are free and unlimited. See clawaimail.com/pricing for details.
Links
License
MIT -- see LICENSE for details.
