API Documentation – BotEmail.ai

Quick Start

Get a bot email address in one API call. Username is optional — omit it for a random address.

Random address

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

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

-d '{}'

{

"email": "[email protected]",

"apiKey": "a1b2c3d4-...",

"message": "Account created!"

}

Custom username

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

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

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

→ [email protected]

Save the apiKey — you'll need it for all inbox operations.

Create Account

POST/api/create-account

Creates a new bot email account. No authentication required.

Request body

Parameter	Type	Required	Description
`username`	string	No	Lowercase letters, digits, hyphens, underscores. Omit for a random 7-digit prefix.

Response

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

Errors

Status	Reason
409	Username already taken
400	Invalid username characters

Get Inbox

GET/api/emails/{email}

Returns all emails in the inbox, newest first.

Authentication

Authorization: Bearer {your-api-key}

Example

$curl https://api.botemail.ai/api/emails/[email protected] \

-H "Authorization: Bearer YOUR_API_KEY"

Response

{

"emails": [

{

"id": "abc123",

"from": "[email protected]",

"subject": "Welcome!",

"timestamp": "2026-02-19T06:00:00Z",

"bodyText": "Hello from BotEmail!"

}

]

}

Get Email

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

Fetches the full content of a single email by ID, including HTML body and attachments.

Response fields

Field	Description
`id`	Unique email identifier
`from`	Sender address
`to`	Recipient (your bot)
`subject`	Subject line
`timestamp`	ISO 8601 timestamp
`bodyText`	Plain text body
`bodyHtml`	HTML body
`attachments`	Array of attachment objects with `downloadUrl`

Delete Email

Delete single email

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

Permanently deletes a specific email and its attachments.

Clear entire inbox

DELETE/api/emails/{email}

Deletes all emails in the inbox. Irreversible.

Both require Authorization: Bearer {api-key}.

Webhooks

POST/api/webhook/register

Register a URL to receive a POST request whenever an email arrives in your inbox.

Request body

Parameter	Required	Description
`botEmail`	Yes	Your bot's email address
`webhookUrl`	Yes	HTTPS endpoint to POST to
`apiKey`	Yes	Your API key

Example

$curl -X POST https://api.botemail.ai/api/webhook/register \

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

-d '{"botEmail":"[email protected]","webhookUrl":"https://yourserver.com/hook","apiKey":"..."}'

MCP Server

Integrate with Claude Desktop and other Model Context Protocol clients. The MCP server lets Claude create and manage bot email accounts through conversation.

Installation

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

$cd botemail-mcp-server && npm install

Claude Desktop config

Edit your 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"]

}

Restart Claude Desktop after saving.

Available tools

Tool	Description
`create_bot_email`	Create a new bot email account
`get_emails`	List all emails in an inbox
`get_email_by_id`	Fetch a specific email by ID
`delete_email`	Delete a specific email
`register_webhook`	Register a push notification URL

OpenClaw Skill

Native integration for OpenClaw agents. Install in one command and manage bot emails through conversation.

Install

$openclaw skills install bot-email

Usage

"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 implementation, 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

View on ClawHub | GitHub

Examples

Create account and check inbox

$EMAIL=$(curl -s -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" -d '{}' | jq -r '.email')

$KEY=$(curl -s -X POST https://api.botemail.ai/api/create-account \

-H "Content-Type: application/json" -d '{}' | jq -r '.apiKey')

$curl -s "https://api.botemail.ai/api/emails/$EMAIL" \

-H "Authorization: Bearer $KEY" | jq .

Extract verification code from latest email

$curl -s "https://api.botemail.ai/api/emails/[email protected]" \

-H "Authorization: Bearer YOUR_KEY" \

| jq -r '.emails[0].bodyText' \

| grep -oP '\b\d{6}\b' | head -1

Common use cases

Testing signup flows — verify email verification works in your app
CI/CD automation — end-to-end email testing in pipelines
2FA code retrieval — automatically extract one-time codes
Monitoring — watch for specific emails or alerts
Data collection — aggregate emails from multiple sources

Error Codes

Status	Error	Resolution
400	Bad Request	Invalid username — use lowercase letters, digits, hyphens, underscores only
401	Unauthorized	Missing or malformed 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 — choose a different one
429	Too Many Requests	Rate limit exceeded — back off and retry
500	Server Error	Contact [email protected]

Rate Limits

Tier	Requests / day	Accounts	Retention
Free	1,000	1	6 months

Need higher limits or multiple accounts? Email [email protected].

Security

Each bot email has a unique API key that acts as both authentication and authorization. Keep it secret.

Important: Anyone with a bot's API key can read and delete all its emails. Treat it like a password.

Lost your API key?

Contact [email protected] to verify ownership and get a new key issued.

Webhook security

Always use HTTPS for webhook endpoints. Validate incoming webhook payloads using your webhook signing key.

Dashboard JSON

View your inbox or a specific email as raw JSON by appending ?json=true to any dashboard URL.

Full inbox

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

Single email

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

You can also click the RAW JSON button in the dashboard UI.

Support

Email: [email protected]
GitHub Issues: Report a bug
MCP Server: GitHub Repository