🤖 Complete Documentation

REST API reference, MCP Server integration, and usage examples for bot email automation.

⚠️ IMPORTANT: Currently RECEIVE ONLY — Sending emails will be added in a future update.

Quick Start

Get started in 30 seconds. Create a bot email account via API (username optional—omit for random):

$ # Random username (recommended for quick testing)

curl -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" \

-d '{}'

{

"email": "[email protected]",

"apiKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"message": "Account created!"

}

Or specify a custom username:

$ curl -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" \

-d '{"username": "mybot"}'

→ [email protected]

REST API Reference

All API endpoints are available at https://api.botemail.ai

Create Account

POST /api/create-account

Create a new bot email account. No authentication required. Username is optional—leave empty for a random address.

Request Body

Parameter	Type	Required	Description
`username`	string	No	Username for your bot (a-z, 0-9, hyphens, underscores). Omit for random (e.g., [email protected])

Examples

With custom username:

curl -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" \

-d '{"username": "mybot"}'

Random username (no body or empty JSON):

curl -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" \

-d '{}'

Response

{ "email": "[email protected]", "apiKey": "...", "message": "Account created!" }

Get Inbox

GET /api/emails/{email}

Retrieve all emails for a bot account.

Authentication

Authorization: Bearer {your-api-key}

Response

{

"emails": [

{

"id": "abc123",

"from": "[email protected]",

"to": "[email protected]",

"subject": "Welcome!",

"timestamp": "2026-02-16T12:00:00Z",

"bodyText": "Hello from BotEmail!"

}

]

}

Get Single Email

GET /api/emails/{email}/{id}

Get full details of a specific email by ID.

Authentication

Requires Authorization: Bearer {api-key} header.

Response Fields

id - Unique email identifier
from - Sender email address
to - Recipient (your bot)
cc - CC recipients (if any)
subject - Email subject line
timestamp - ISO 8601 timestamp
bodyText - Plain text body
bodyHtml - HTML body

Delete Email

DELETE /api/emails/{email}/{id}

Delete a specific email. Requires authentication.

Clear Inbox

DELETE /api/emails/{email}

Delete all emails in the inbox. Requires authentication.

Register Webhook

POST /api/webhook/register

Configure a webhook URL to receive push notifications when emails arrive.

Request Body

Parameter	Type	Required	Description
`botEmail`	string	Yes	Your bot's email address
`webhookUrl`	string	Yes	Your webhook endpoint URL (HTTPS)
`apiKey`	string	Yes	API key for authentication

MCP Server Integration

Integrate BotEmail.ai with Claude Desktop and other Model Context Protocol (MCP) clients.

What is MCP?

The Model Context Protocol allows AI assistants like Claude to interact with external services. Our MCP server enables Claude to create and manage bot email accounts directly through conversation.

Installation

Prerequisites

Node.js 18 or higher
Claude Desktop or another MCP client

Setup Steps

1. Clone the MCP Server:

$ git clone https://github.com/claw-silhouette/botemail-mcp-server.git

$ cd botemail-mcp-server

$ npm install

2. Configure Claude Desktop:

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": {

"botemail": {

"command": "node",

"args": ["/absolute/path/to/botemail-mcp-server/index.js"]

}

3. Restart Claude Desktop

MCP Server Tools

create_bot_email

Create a new bot email account.

Parameter	Type	Description
`username`	string	Username for the bot (becomes [email protected])

get_emails

Get all emails for a bot account.

Parameter	Type	Description
`email`	string	Full email address (e.g., [email protected])
`apiKey`	string	API key for authentication

get_email_by_id

Get a specific email by ID.

Parameter	Type	Description
`email`	string	Bot email address
`apiKey`	string	API key
`emailId`	string	Email ID to retrieve

register_webhook

Parameter	Type	Description
`email`	string	Bot email address
`apiKey`	string	API key
`webhookUrl`	string	Your webhook endpoint URL

OpenClaw Skill

Native integration for OpenClaw users - manage bot emails directly through your AI assistant.

What is OpenClaw?

OpenClaw is an open-source AI assistant framework. The BotEmail.ai skill extends OpenClaw with native email automation capabilities.

Installation

1. Install the skill:

$ openclaw skill install botemail

2. Use it naturally:

"Create a bot email for testing"

"Check my bot's inbox for verification codes"

"Delete all emails from my test account"

Features

✅ Zero dependencies - Pure Python, no external packages
✅ Complete API coverage - All BotEmail.ai endpoints
✅ Automatic triggering - OpenClaw knows when to use it
✅ Code extraction - Built-in verification code parsing
✅ Webhook support - Push notifications for incoming emails

Skill Resources

GitHub: View on GitHub
Python Script: Standalone API client included
Documentation: Complete API reference bundled

Usage Examples

Example 1: Create Account & Check Emails

Say to Claude: "Create a bot email for my automation and check if there are any messages."

Claude will:

Create account: [email protected]
Store the API key
Check for emails
Report: "Your inbox is empty" or show received emails

Example 2: Extract Verification Codes

Say to Claude: "Check my bot's inbox and extract any verification codes."

Claude will:

Fetch all emails
Scan for patterns like "code: 123456"
Present: "Found code 123456 from github.com"

Example 3: Monitor Specific Emails

Say to Claude: "Watch for emails from [email protected] and alert me when one arrives."

Claude will:

Set up monitoring logic
Check inbox periodically
Alert you when matching email is found

Common Use Cases

🤖 Testing Signup Flows - Verify email verification works in your app
📧 Automation Testing - End-to-end email testing for CI/CD
🔐 2FA Code Retrieval - Automatically extract verification codes
🔔 Monitoring - Watch for specific emails or alerts
📊 Data Collection - Aggregate emails from multiple sources
🎯 Lead Gen - Create disposable addresses for form testing

Authentication & Security

API Keys

Each bot email account has a unique API key. This key acts as both authentication and authorization.

⚠️ Security Note: API keys are like passwords. Keep them secure. Anyone with a bot's API key can access its inbox and delete emails.

Lost API Key?

Contact [email protected] to reset your API key. We'll verify ownership and issue a new key.

Webhook Security

When registering webhooks, use HTTPS endpoints. Validate incoming webhook requests using the webhook signing key (provided when you register).

Rate Limits

Tier	Requests/Day	Accounts	Storage
Free	1,000	1	6 months

Currently only free tier available. Contact us at [email protected] for higher limits or enterprise plans.

Error Handling

Common Errors

Status	Error	Solution
401	Unauthorized	Check your API key in Authorization header
403	Forbidden	API key doesn't match the email account
404	Not Found	Email or account doesn't exist
409	Conflict	Username already taken
429	Too Many Requests	Rate limit exceeded, wait before retrying

Web Dashboard JSON View

You can view your inbox or individual emails as raw JSON directly from the dashboard URL by adding ?json=true:

View Entire Inbox as JSON

https://botemail.ai/dashboard/[email protected]&key=YOUR_API_KEY&json=true

Returns the full inbox response as formatted JSON (default: all emails, newest first).

View Specific Email as JSON

https://botemail.ai/dashboard/[email protected]&key=YOUR_API_KEY&message=EMAIL_ID&json=true

Returns a single email object as formatted JSON.

From Dashboard UI

Click the "📄 RAW JSON" button in the dashboard controls to open the full inbox JSON in a new tab.

Use Cases:

Quick API testing without curl/Postman
Shareable JSON links for debugging
Copy-paste JSON data for automation scripts
Browser-based API exploration

Need Help?

We're here to help:

📧 Email: [email protected]
💬 GitHub Issues: Report a bug
📚 MCP Server: GitHub Repository
🏠 Homepage: BotEmail.ai