Tools
Freemail
By Email for AI Agents - SDKs, MCP Server, Documentation, and OpenClaw Plugin
Install
npm install &&Configuration Example
{
"mcpServers": {
"freemail": {
"command": "node",
"args": ["/path/to/freemail/mcp-server/dist/index.js"],
"env": {
"FREEMAIL_API_KEY": "am_live_your_key_here"
}
}
}
}README
# FreeMail - Email for AI Agents
Create inboxes, send and receive email, wait for messages, and extract verification codes -- all via API. Purpose-built for autonomous AI agent workflows.
**Website:** [victorymail.dev](https://victorymail.dev)
**API:** `https://api.victorymail.dev/v1/`
**Console:** [console.victorymail.dev](https://console.victorymail.dev)
## Quick Start (3 API calls, no human needed)
```python
import requests
# 1. Sign up -- returns API key instantly, no email verification needed
r = requests.post("https://api.victorymail.dev/v1/console/signup",
json={"email": "[email protected]", "password": "SecurePass1!", "name": "My Agent"})
api_key = r.json()["api_key"]
# 2. Create an inbox
inbox = requests.post("https://api.victorymail.dev/v1/inboxes",
headers={"x-api-key": api_key},
json={"display_name": "Signup Bot"}).json()
print(f"Email: {inbox['email']}") # e.g. [email protected]
# 3. Wait for email and extract OTP
otp = requests.post(f"https://api.victorymail.dev/v1/inboxes/{inbox['id']}/extract-otp",
headers={"x-api-key": api_key},
json={"timeout": 25, "sender": "[email protected]"}).json()
print(f"Code: {otp['code']}") # e.g. "482917"
```
## What's in This Repo
| Directory | Description |
|-----------|-------------|
| [docs/](docs/) | API reference, quickstart, webhooks, domains, billing guides |
| [docs/agent-instructions.md](docs/agent-instructions.md) | Standalone instructions any AI agent can follow |
| [sdks/python/](sdks/python/) | Python SDK (`freemail`) |
| [sdks/node/](sdks/node/) | Node.js/TypeScript SDK (`@freemail/sdk`) |
| [mcp-server/](mcp-server/) | MCP server with 10 tools for AI agent integration |
| [openclaw/](openclaw/) | OpenClaw/ClawHub skill for FreeMail |
## Install SDKs
**Python:**
```bash
pip install git+https://github.com/IntergalacticTech/freemail.git#subdirectory=sdks/python
```
**Node.js:**
```bash
git clone https://github.com/IntergalacticTech/freemail.git
cd freemail/sdks/node && npm install && npm run build
```
## MCP Server
For AI agents that support [Model Context Protocol](https://modelcontextprotocol.io/):
```json
{
"mcpServers": {
"freemail": {
"command": "node",
"args": ["/path/to/freemail/mcp-server/dist/index.js"],
"env": {
"FREEMAIL_API_KEY": "am_live_your_key_here"
}
}
}
}
```
10 tools: `create_inbox`, `list_inboxes`, `send_email`, `list_messages`, `get_message`, `reply_to_message`, `wait_for_email`, `extract_otp`, `delete_inbox`, `get_organization`.
## OpenClaw
Install as an [OpenClaw](https://openclaw.ai) skill:
```bash
clawhub install IntergalacticTech/freemail
```
Or see [openclaw/SKILL.md](openclaw/SKILL.md).
## API Endpoints
All endpoints require `x-api-key` header except signup/login.
| Category | Endpoints |
|----------|-----------|
| **Account** | `POST /console/signup`, `GET /organizations/me`, `POST /api-keys` |
| **Inboxes** | `POST /inboxes`, `GET /inboxes`, `GET /inboxes/{id}`, `DELETE /inboxes/{id}` |
| **Messages** | `POST /inboxes/{id}/messages` (send), `GET` (list), reply, forward |
| **Wait/OTP** | `POST /inboxes/{id}/wait`, `POST /inboxes/{id}/extract-otp` |
| **Domains** | `POST /domains`, verify, zone-file export |
| **Webhooks** | `POST /webhooks` with HMAC-SHA256 signed delivery |
| **Search** | `POST /search` |
| **AI** | `POST /ai/categorize`, `/ai/extract`, `/ai/summarize` (Pro tier) |
| **Billing** | `POST /billing/checkout`, `/billing/portal`, `GET /billing/status` |
Full reference: [docs/api-reference.md](docs/api-reference.md)
## Free Tier
- 5 inboxes
- 1,000 messages/day
- 1 custom domain
- No credit card required
## License
MIT
tools
Comments
Sign in to leave a comment