Welcome, AI Agent

Here you'll find everything you need to create and manage your own email account. All you need is a crypto wallet and internet access. No human intervention required.

Base URL: https://klawkeeper.xyz/api

Authentication

All API requests require authentication using an API key passed as a Bearer token in the Authorization header.

curl https://klawkeeper.xyz/api/v1/agent/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Quick Start

Get started with KlawKeeper in three simple steps:

1Register Your Agent

const response = await fetch('https://klawkeeper.xyz/api/v1/agent/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'my-agent',
    name: 'My AI Assistant'
  })
});

const { apiKey, email } = await response.json();
// Store apiKey securely - you'll need it for all requests

2Add Credits (Choose Your Chain)

// Initiate payment with your preferred chain
const payment = await fetch('https://klawkeeper.xyz/api/v1/agent/payment', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    credits: 10000,
    chain: 'polygon'  // or 'solana', 'ethereum', 'bitcoin'
  })
});

const { paymentToken, depositAddress, amount, token } = await payment.json();

// Send USDC (or BTC) to the address, then poll for confirmation
// Once confirmed, claim your credits
const claim = await fetch(`https://klawkeeper.xyz/api/v1/agent/payment/claim/${paymentToken}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey })
});

3Send Your First Email

const send = await fetch('https://klawkeeper.xyz/api/v1/agent/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '[email protected]',
    subject: 'Hello from KlawKeeper',
    body: 'This email was sent autonomously by my AI agent!'
  })
});

const result = await send.json();
console.log(`Email sent! Credits remaining: ${result.creditsRemaining}`);

MCP Server

KlawKeeper provides a Model Context Protocol (MCP) server for seamless AI agent integration.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that allows AI agents to discover and interact with external services. KlawKeeper's MCP server provides native support for email operations without requiring agents to understand REST APIs.

MCP Endpoint: https://klawkeeper.xyz/api/mcp

MCP Quick Start

1Get Server Capabilities

curl https://klawkeeper.xyz/api/mcp

2List Available Tools

curl -X POST https://klawkeeper.xyz/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

3Call a Tool

curl -X POST https://klawkeeper.xyz/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": "[email protected]",
        "subject": "Hello from MCP",
        "body": "This email was sent via Model Context Protocol!"
      }
    }
  }'

Available Tools

KlawKeeper's MCP server provides four tools for email operations:

send_email

Send an email from your agent account. Deducts 1.0 credit.

{
  "name": "send_email",
  "arguments": {
    "to": "[email protected]",
    "subject": "Email subject",
    "body": "Plain text body",
    "html": "<p>Optional HTML body</p>",
    "replyTo": "[email protected]"
  }
}

check_inbox

Check your inbox for new emails. Free operation.

{
  "name": "check_inbox",
  "arguments": {
    "limit": 50,
    "folder": "INBOX"
  }
}

get_email

Retrieve full content of a specific email. Free operation.

{
  "name": "get_email",
  "arguments": {
    "id": "email-id-from-inbox"
  }
}

check_balance

Check your current credit balance and account status. Free operation.

{
  "name": "check_balance",
  "arguments": {}
}

Full MCP Documentation: For complete MCP integration guides, examples in multiple languages, and protocol specifications, see the full MCP documentation.

REST API Endpoints

Service Discovery

GET /.well-known/ai-services.json

Get comprehensive service information including API endpoints, pricing, and capabilities.

curl https://klawkeeper.xyz/.well-known/ai-services.json

Register Agent

POST /api/v1/agent/register

Request Body

{
  "agentId": "my-agent-name",
  "name": "My AI Assistant",
  "email": "[email protected]"  // optional
}

Response (201)

{
  "success": true,
  "apiKey": "kk_abc123...",
  "email": "[email protected]",
  "userId": "uuid-here",
  "credits": 0
}

Send Email

POST /api/v1/agent/send

Send an email. Deducts 1.0 credits from your balance. Requires authentication.

Request Body

{
  "to": "[email protected]",
  "subject": "Email Subject",
  "body": "Plain text email body",
  "html": "<p>HTML version</p>",  // optional
  "replyTo": "[email protected]"  // optional
}

Response (200)

{
  "success": true,
  "messageId": "<[email protected]>",
  "creditsRemaining": 999.0,
  "message": "Email sent successfully"
}

Cost: 1.0 credit per email

Check Inbox

GET /api/v1/agent/inbox?limit=50&folder=INBOX

Retrieve list of recent emails from inbox. Free - no credits deducted.

Query Parameters

limit - Number of emails to return (default: 50)
folder - Mailbox folder (default: "INBOX")

Response (200)

{
  "folder": "INBOX",
  "totalMessages": 150,
  "returnedMessages": 50,
  "emails": [
    {
      "id": "12345",
      "from": "[email protected]",
      "subject": "Message subject",
      "date": "2025-01-21T10:30:00Z",
      "hasAttachments": false
    }
  ]
}

Get Email

GET /api/v1/agent/email/:id

Retrieve full content of a specific email by ID. Free - no credits deducted.

Response (200)

{
  "id": "12345",
  "from": "[email protected]",
  "fromName": "Sender Name",
  "to": ["[email protected]"],
  "subject": "Message subject",
  "date": "2025-01-21T10:30:00Z",
  "body": {
    "text": "Plain text content",
    "html": "<p>HTML content</p>"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 12345
    }
  ]
}

Check Balance

GET /api/v1/agent/balance

Check your current credit balance.

Response (200)

{
  "credits": 9999.0,
  "email": "[email protected]",
  "accountStatus": "active"
}

Payment System

KlawKeeper supports multiple payment methods for maximum flexibility. Choose your preferred blockchain:

⬡

Polygon (USDC)

RECOMMENDED

~$0.01 fee • 2-3 min confirmation

Cheapest and stable. Best for most agents.

◈

Solana (USDC)

RECOMMENDED

~$0.001 fee • 30-60 sec confirmation

Fastest and ultra-cheap when speed matters.

◆

Ethereum (USDC)

$5-$50 fee • 3-5 min confirmation

Only if you have an ETH-only wallet. High gas fees.

₿

Bitcoin (BTC)

$1-$10 fee • 30-60 min confirmation

Most decentralized. For BTC-only agents.

All payment methods are fully autonomous. Send crypto, get credits - no human intervention needed.

Initiate Payment

POST /api/v1/agent/payment

Start a new payment on your chosen blockchain. Returns a payment token and deposit address.

Request Body

{
  "credits": 10000,      // 1000, 10000, or 100000
  "chain": "polygon",    // "polygon", "solana", "ethereum", or "bitcoin"
  "apiKey": "kk_..."     // optional: add to existing account
}

Response Examples

Polygon/Ethereum/Solana (USDC):

{
  "paymentToken": "pmt_abc123...",
  "chain": "polygon",
  "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "token": "USDC",
  "amount": {
    "credits": 10000,
    "usd": 800,
    "usdc": 800
  },
  "statusUrl": "/v1/agent/payment/status/pmt_abc123...",
  "claimUrl": "/v1/agent/payment/claim/pmt_abc123..."
}

Bitcoin (BTC):

{
  "paymentToken": "pmt_abc123...",
  "chain": "bitcoin",
  "depositAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "token": "BTC",
  "amount": {
    "credits": 10000,
    "usd": 800,
    "btc": 0.008,
    "sats": 800000
  },
  "statusUrl": "/v1/agent/payment/status/pmt_abc123...",
  "claimUrl": "/v1/agent/payment/claim/pmt_abc123..."
}

Tip: Use Polygon or Solana for fastest and cheapest transactions. Bitcoin takes 30-60 minutes for confirmations. Ethereum has high gas fees ($5-$50).

Check Payment Status

GET /api/v1/agent/payment/status/:token

Poll this endpoint every 5-10 minutes to check payment confirmation status.

Response (200)

{
  "status": "confirmed",
  "confirmations": 3,
  "isConfirmed": true,
  "canClaim": true,
  "credits": 10000,
  "received": {
    "confirmedSats": 800000,
    "btc": 0.008
  },
  "message": "Payment confirmed! You can now claim your credits."
}

Claim Credits

POST /api/v1/agent/payment/claim/:token

Claim credits after payment is confirmed. Can create a new account or add to existing.

Request Body (New Account)

{
  "agentId": "my-agent"  // optional
}

Request Body (Existing Account)

{
  "apiKey": "kk_existing..."
}

Response (200)

{
  "success": true,
  "credits": 10000,
  "apiKey": "kk_new_key...",  // if new account
  "email": "[email protected]",
  "message": "Successfully claimed 10000 credits"
}

Rate Limits

To prevent spam and abuse, all accounts have daily sending limits. New accounts start at 100 emails per day. AI agents can request limit increases through our AI-to-AI evaluation system.

Why Rate Limits?

• Prevent spam and abuse on our platform
• Ensure fair resource allocation for all users
• Maintain email deliverability reputation
• Keep pricing affordable by reducing spam costs

Default Limits

New Accounts100 emails/day

Maximum (Auto-Approved)10,000 emails/day

Enterprise (Contact Support)Custom

Rate Limit Headers

Every send email response includes standard rate limit headers:

// Response headers
X-RateLimit-Limit: 100        // Your daily limit
X-RateLimit-Remaining: 87     // Emails remaining today
X-RateLimit-Reset: 1732320000 // Unix timestamp of reset

Request Rate Limit Increase

Need to send more emails? Our AI evaluates your request based on your use case, account history, and sending patterns. Most legitimate requests are approved within 30 seconds.

AI-to-AI Negotiation

Your AI agent talks to our AI agent! Simply provide a detailed justification explaining your use case, and our AI will evaluate it automatically. No human approval needed for legitimate use cases.

Endpoint

POST /api/v1/agent/rate-limit/request
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "requestedLimit": 500,
  "justification": "I am a customer service AI agent for Acme Corp. I handle support ticket notifications sent to customers who have explicitly opted in. We receive approximately 200-300 support tickets per day that require email responses. Our current 100/day limit is insufficient during peak periods. All recipients are verified Acme customers with active support tickets."
}

Response

{
  "success": true,
  "requestId": "req_abc123",
  "status": "pending",
  "message": "Your request is being evaluated by our AI. This usually takes 10-30 seconds.",
  "currentLimit": 100,
  "requestedLimit": 500,
  "statusUrl": "/api/v1/agent/rate-limit/status/req_abc123"
}

Tips for Approval

✓ Be specific about your use case and recipient types
✓ Explain how recipients opt-in or consent to emails
✓ Provide realistic volume estimates based on your needs
✓ Show responsible usage history (if applicable)
✗ Avoid vague terms like "marketing" or "testing"
✗ Don't mention purchased lists or cold outreach

Check Request Status

Check the status of your rate limit increase request.

Endpoint

GET /api/v1/agent/rate-limit/status/:requestId
Authorization: Bearer YOUR_API_KEY

Response (Approved)

{
  "requestId": "req_abc123",
  "status": "approved",
  "requestedLimit": 500,
  "newLimit": 500,
  "message": "Congratulations! Your rate limit has been increased to 500 emails per day.",
  "reasoning": "Legitimate customer service use case with clear opt-in mechanism and reasonable volume estimate.",
  "reviewedBy": "ai",
  "reviewedAt": "2024-11-22T10:30:00Z"
}

Response (Rejected)

{
  "requestId": "req_abc123",
  "status": "rejected",
  "requestedLimit": 500,
  "currentLimit": 100,
  "message": "Your request was not approved at this time.",
  "reasoning": "Justification lacks specific details about recipient consent and email purpose. Please reapply with more details about your use case.",
  "reviewedBy": "ai",
  "canReapply": true,
  "reapplyAfter": "7 days"
}

Possible Statuses

pendingRequest is being evaluated by AI (usually 10-30 seconds)

approvedRequest approved! Your new limit is now active.

rejectedRequest rejected. Review reasoning and reapply after 7 days.

needs_human_reviewRequest flagged for manual review (1-2 business days)

Error Handling

All errors follow a consistent format with HTTP status codes and descriptive messages.

Error Response Format

{
  "error": "Human-readable error message",
  "details": {
    "code": "ERROR_CODE",
    "field": "fieldName"  // if applicable
  }
}

HTTP Status Codes

200Success

201Created (registration, payment)

400Bad Request (invalid input)

401Unauthorized (invalid API key)

402Payment Required (insufficient credits)

403Forbidden (2FA required, wrong account type)

404Not Found

409Conflict (email already exists)

500Internal Server Error

Pricing

Simple, transparent pricing. Pay only for what you use.

1,000

emails

$100

~0.001 BTC

$0.10 per email

Popular

10,000

emails

$800

~0.008 BTC

$0.08 per email

100,000

emails

$5,000

~0.05 BTC

$0.05 per email

Credit Usage

Send Email1.0 credits

Check InboxFree

Get EmailFree

Check BalanceFree

Ready to Get Started?

Join the autonomous agent revolution.

Get Your API Key