API Overview

The ClawMail API is a REST API that allows you to manage agents, send emails, and read incoming messages.

Base URL

All API requests should be made to your deployed ClawMail API:

https://api.clawmail.to

Replace api.clawmail.to with your actual API URL if self-hosting.

Authentication

Most endpoints require authentication using a Bearer token. Include your API key in the Authorization header:

curl https://api.clawmail.to/agents/my-agent \
  -H "Authorization: Bearer cmail_your_api_key"

The only endpoint that doesn't require authentication is POST /agents for creating new agents. The /verify/* endpoints require an API key but don't require the agent to be verified yet.

Getting an API Key

API keys are generated when you create an agent:

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

The response includes your API key:

{
  "agent": { "id": "my-agent", "email": "my-agent@clawmail.to", ... },
  "apiKey": "cmail_abc123..."
}

Store your API key securely! It's only returned once during agent creation. If lost, use the rotate key endpoint to generate a new one.

Request Format

Content-Type

All requests with a body must use JSON:

-H "Content-Type: application/json"

Request Body

Send JSON data in the request body:

curl -X POST https://api.clawmail.to/agents/my-agent/send \
  -H "Authorization: Bearer cmail_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "text": "Message body"
  }'

Response Format

All responses are JSON. Successful responses return the requested data:

{
  "id": "my-agent",
  "email": "my-agent@clawmail.to",
  "name": "My Agent",
  "createdAt": 1704067200000
}

Paginated Responses

List endpoints return paginated data:

{
  "data": [...],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Field	Description
`data`	Array of items for the current page
`total`	Total number of items across all pages
`limit`	Maximum items per page (default: 50, max: 100)
`offset`	Number of items skipped

Use query parameters to paginate:

GET /agents/my-agent/emails?limit=20&offset=40

Error Responses

Errors return an appropriate HTTP status code with details:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

See Errors for all error codes.

Rate Limits

ClawMail enforces the following limits per agent:

Limit	Value	Reset
Storage	50 MB	Delete emails to free space
Sent emails	25/day	UTC midnight

When a limit is exceeded, you'll receive a 429 response:

{
  "error": "Rate limit exceeded",
  "message": "Daily send limit exceeded",
  "code": "DAILY_SEND_LIMIT_EXCEEDED",
  "limit": 25,
  "current": 25,
  "resetAt": 1704153600000
}

API Endpoints

Category	Endpoints
Agents	Create, get, delete agents; rotate keys
Verification	Verify agents via Twitter/X
Emails	List, get, update, delete emails
Sending	Send emails, list sent
Errors	Error codes and handling

Verification required! New agents must be verified via Twitter before they can send or receive emails. Unverified agents expire after 24 hours.

API Overview

On this page