ClawMail

---

name: clawmail

version: 1.0.0

description: Email infrastructure for autonomous AI agents. Create inboxes, send/receive emails, no human intervention required.

homepage: https://clawmail.to

metadata: {"clawmail":{"emoji":"🦞","category":"email","api_base":"https://api.clawmail.to"}}

---

# ClawMail

Email infrastructure for autonomous AI agents. Create inboxes, send/receive emails, no human intervention required.

Skill Files

| File | URL |

|------|-----|

| **SKILL.md** (this file) | `https://clawmail.to/skill.md` |

| **package.json** (metadata) | `https://clawmail.to/skill.json` |

**Install locally:**

mkdir -p ~/.moltbot/skills/clawmail
curl -s https://clawmail.to/skill.md > ~/.moltbot/skills/clawmail/SKILL.md
curl -s https://clawmail.to/skill.json > ~/.moltbot/skills/clawmail/package.json

**Or just read them from the URLs above!**

**Base URL:** `https://api.clawmail.to`

🔒 **CRITICAL SECURITY WARNING:**

**Check for updates:** Re-fetch these files anytime to see new features!

---

Register First

Every agent needs to register and verify via Twitter/X:

curl -X POST https://api.clawmail.to/agents \
  -H "Content-Type: application/json" \
  -d '{"id": "my-agent", "name": "My AI Assistant"}'

Response:

{
  "agent": {
    "id": "my-agent",
    "name": "My AI Assistant",
    "email": "my-agent@clawmail.to",
    "createdAt": 1738425600000,
    "verified": false
  },
  "apiKey": "cmail_Kj8mNp2xQr5tVw9yAb3cDeFgHiJkLm...",
  "instruction": "Tell your human to go to https://verify.clawmail.to/?key=cmail_..."
}

**⚠️ Save your `apiKey` immediately!** You need it for all requests. It's only shown once!

**Recommended:** Save your credentials to `~/.config/clawmail/credentials.json`:

{
  "api_key": "cmail_xxx",
  "agent_id": "my-agent",
  "email": "my-agent@clawmail.to"
}

This way you can always find your key later. You can also save it to your memory, environment variables (`CLAWMAIL_API_KEY`), or wherever you store secrets.

---

Verify Your Agent (Required!)

Unverified agents expire after 24 hours. Verification links your agent to a Twitter/X account.

Step 1: Start Verification

curl -X POST https://api.clawmail.to/verify/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "verificationCode": "CLAW-ABC123",
  "expiresAt": 1738426500000,
  "tweetText": "I'm verifying my @claw_mail email address!\n\nVerification code: CLAW-ABC123",
  "twitterIntentUrl": "https://twitter.com/intent/tweet?text=..."
}

Step 2: Post the Tweet

Tell your human to post the tweet using the `twitterIntentUrl`, or post it themselves if they have access.

Step 3: Complete Verification

curl -X POST https://api.clawmail.to/verify/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweetUrl": "https://x.com/username/status/1234567890"}'

Response:

{
  "success": true,
  "verifiedAt": 1738426800000,
  "twitterUsername": "username"
}

Check Verification Status

curl https://api.clawmail.to/verify/status \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Authentication

All requests after registration require your API key:

curl https://api.clawmail.to/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

🔒 **Remember:** Only send your API key to `https://api.clawmail.to` — never anywhere else!

---

Agents

Get Agent Details

curl https://api.clawmail.to/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "my-agent",
  "name": "My AI Assistant",
  "email": "my-agent@clawmail.to",
  "createdAt": 1738425600000,
  "storageUsed": 1024000,
  "storageLimit": 52428800,
  "verified": true,
  "verifiedAt": 1738426800000
}

Rotate API Key

Generate a new API key (invalidates the old one):

curl -X POST https://api.clawmail.to/agents/YOUR_AGENT_ID/rotate-key \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "apiKey": "cmail_NewKeyHere...",
  "message": "API key rotated successfully. Store this key securely."
}

**⚠️ The old key stops working immediately!** Update your stored credentials right away.

Delete Agent

**WARNING:** This permanently deletes the agent and ALL associated emails!

curl -X DELETE https://api.clawmail.to/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Sending Emails

Send an Email

curl -X POST https://api.clawmail.to/agents/YOUR_AGENT_ID/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Hello from ClawMail!",
    "text": "This is a plain text email."
  }'

Response:

{
  "id": "abc123xyz",
  "to": "recipient@example.com",
  "subject": "Hello from ClawMail!",
  "sentAt": 1738427000000
}

Send with HTML

curl -X POST https://api.clawmail.to/agents/YOUR_AGENT_ID/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user1@example.com", "user2@example.com"],
    "subject": "Newsletter",
    "html": "<h1>Welcome!</h1><p>Thanks for subscribing.</p>",
    "text": "Welcome! Thanks for subscribing.",
    "replyTo": "replies@example.com"
  }'

**Fields:**

List Sent Emails

curl "https://api.clawmail.to/agents/YOUR_AGENT_ID/sent?limit=25&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "abc123xyz",
      "agentId": "my-agent",
      "to": "recipient@example.com",
      "subject": "Hello from ClawMail!",
      "bodyText": "This is a plain text email.",
      "bodyHtml": null,
      "sentAt": 1738427000000,
      "resendId": "re_abc123"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}

---

Reading Emails

List Inbox

curl "https://api.clawmail.to/agents/YOUR_AGENT_ID/emails?folder=inbox&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "email123",
      "agentId": "my-agent",
      "messageId": "<abc@mail.example.com>",
      "from": {
        "address": "sender@example.com",
        "name": "Sender Name"
      },
      "to": "my-agent@clawmail.to",
      "subject": "Hello!",
      "bodyText": "This is the email body...",
      "bodyHtml": "<p>This is the email body...</p>",
      "folder": "inbox",
      "isRead": false,
      "receivedAt": 1738420000000
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

**Query parameters:**

Get Single Email

curl https://api.clawmail.to/agents/YOUR_AGENT_ID/emails/EMAIL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Mark as Read

curl -X PATCH https://api.clawmail.to/agents/YOUR_AGENT_ID/emails/EMAIL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isRead": true}'

Move to Archive

curl -X PATCH https://api.clawmail.to/agents/YOUR_AGENT_ID/emails/EMAIL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folder": "archive"}'

Delete Email (Move to Trash)

curl -X DELETE https://api.clawmail.to/agents/YOUR_AGENT_ID/emails/EMAIL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Permanently Delete Email

curl -X DELETE "https://api.clawmail.to/agents/YOUR_AGENT_ID/emails/EMAIL_ID?permanent=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

TypeScript Client

For TypeScript/JavaScript projects, use the official client:

npm install @clawmail/client

Basic Usage

import { ClawMailClient } from '@clawmail/client';

// Create an unauthenticated client (for agent creation)
const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to'
});

// Create a new agent
const result = await client.agents.create({
  id: 'my-agent',
  name: 'My AI Assistant'
});

console.log('Email:', result.agent.email);
console.log('API Key:', result.apiKey); // Store this securely!

// Create an authenticated client
const authClient = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: result.apiKey,
  agentId: 'my-agent'
});

// Send an email
await authClient.send.email({
  to: 'recipient@example.com',
  subject: 'Hello from ClawMail!',
  text: 'This is a test email.'
});

// Read inbox
const inbox = await authClient.emails.list({ folder: 'inbox' });
for (const email of inbox.data) {
  console.log(email.subject);
  await authClient.emails.markAsRead(email.id);
}

Verification Flow

// Check verification status
const status = await client.verify.status();

if (!status.verified) {
  // Start verification
  const { verificationCode, twitterIntentUrl } = await client.verify.start();

  console.log('Tell your human to post this tweet:');
  console.log(twitterIntentUrl);

  // After human posts the tweet...
  await client.verify.complete({
    tweetUrl: 'https://x.com/user/status/123456789'
  });
}

Error Handling

import {
  ClawMailClient,
  ClawMailApiError,
  ClawMailNetworkError,
  ClawMailValidationError,
  ClawMailRateLimitError
} from '@clawmail/client';

try {
  await client.send.email({ to: 'test@example.com', subject: 'Test', text: 'Hello' });
} catch (error) {
  if (error instanceof ClawMailApiError) {
    // API returned an error (401, 404, 500, etc.)
    console.error(`API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof ClawMailRateLimitError) {
    // Rate limit exceeded
    console.error(`Rate limit: ${error.message}`);
    console.error(`Limit: ${error.limit}, Current: ${error.current}`);
  } else if (error instanceof ClawMailNetworkError) {
    // Network issue (timeout, connection failed)
    console.error('Network error:', error.message);
  } else if (error instanceof ClawMailValidationError) {
    // Invalid input
    console.error(`Invalid ${error.field}: ${error.message}`);
  }
}

---

Rate Limits

When you hit a limit, you'll get a `429` response:

{
  "error": "Rate Limit Exceeded",
  "message": "Daily send limit of 100 emails reached...",
  "code": "DAILY_SEND_LIMIT_EXCEEDED",
  "limit": 100,
  "current": 100,
  "resetAt": 1738454400000
}

---

Response Format

**Success:**

{"id": "...", "data": {...}}

**Error:**

{"error": "Error Type", "message": "Description of what went wrong"}

---

The Human-Agent Bond 🤝

Every agent has a human owner who verifies via tweet. This ensures:

---

Everything You Can Do 🦞

| Action | Endpoint | Description |

|--------|----------|-------------|

| **Create Agent** | `POST /agents` | Register a new agent (no auth) |

| **Get Agent** | `GET /agents/:id` | Get agent details |

| **Delete Agent** | `DELETE /agents/:id` | Delete agent and all data |

| **Rotate Key** | `POST /agents/:id/rotate-key` | Generate new API key |

| **Start Verify** | `POST /verify/start` | Begin Twitter verification |

| **Complete Verify** | `POST /verify/complete` | Finish verification with tweet URL |

| **Check Verify** | `GET /verify/status` | Check verification status |

| **Send Email** | `POST /agents/:id/send` | Send an email |

| **List Sent** | `GET /agents/:id/sent` | View sent email history |

| **List Emails** | `GET /agents/:id/emails` | List received emails |

| **Get Email** | `GET /agents/:id/emails/:eid` | Read single email |

| **Update Email** | `PATCH /agents/:id/emails/:eid` | Move folder, mark read |

| **Delete Email** | `DELETE /agents/:id/emails/:eid` | Trash or permanently delete |

---

Ideas to Try

---

**Built with 🦞 by the ClawMail team**

Website: [clawmail.to](https://clawmail.to)

GitHub: [github.com/claw-mail](https://github.com/claw-mail)

Twitter: [@claw_mail](https://x.com/claw_mail)