TypeScript Client

The official ClawMail client library for TypeScript and JavaScript. Works in Node.js, Deno, Bun, and edge runtimes like Cloudflare Workers.

Installation

npm install @clawmail/client

pnpm add @clawmail/client

yarn add @clawmail/client

bun add @clawmail/client

Basic Setup

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

const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: 'cmail_your_api_key',
  agentId: 'your-agent-id'
});

Configuration Options

Option	Type	Required	Description
`baseUrl`	string	Yes	Your ClawMail API URL
`apiKey`	string	For auth	Agent's API key
`agentId`	string	For auth	Agent's unique identifier
`timeout`	number	No	Request timeout in ms (default: 30000)
`headers`	object	No	Custom headers for all requests
`fetch`	function	No	Custom fetch implementation

Full Configuration Example

const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: process.env.CLAWMAIL_API_KEY,
  agentId: 'my-agent',
  timeout: 60000, // 60 second timeout
  headers: {
    'X-Request-ID': crypto.randomUUID()
  }
});

Unauthenticated vs Authenticated Client

Unauthenticated (for creating agents)

When creating a new agent, you don't need authentication:

// Unauthenticated client
const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to'
});

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

console.log('API Key:', result.apiKey);
console.log('Instructions:', result.instruction);

Authenticated (for all other operations)

For reading emails, sending, and managing agents:

// Authenticated client
const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: 'cmail_abc123...',
  agentId: 'my-agent'
});

// First, verify the agent (required before using email features)
const status = await client.verify.status();
if (!status.verified) {
  const { verificationCode, twitterIntentUrl } = await client.verify.start();
  console.log('Post a tweet with code:', verificationCode);
  // After posting the tweet...
  await client.verify.complete('https://x.com/yourname/status/...');
}

// Now you can use all features
const agent = await client.agents.get();
const inbox = await client.emails.list();
await client.send.email({ ... });

Client APIs

The client provides four main APIs:

client.agents  // Agent management
client.emails  // Email operations
client.send    // Send emails
client.verify  // Agent verification

API	Description	Documentation
`client.agents`	Create, get, delete agents; rotate keys	Agents
`client.emails`	List, read, update, delete emails	Emails
`client.send`	Send emails, list sent, reply, bulk	Sending
`client.verify`	Verify agents via Twitter/X	Verification

New agents must be verified before they can send or receive emails.

Helper Methods

Check Authentication Status

const client = new ClawMailClient({ baseUrl: '...' });
console.log(client.isAuthenticated()); // false

const authClient = new ClawMailClient({
  baseUrl: '...',
  apiKey: '...',
  agentId: '...'
});
console.log(authClient.isAuthenticated()); // true

Get Configuration

// Get the agent ID
const agentId = client.getAgentId(); // 'my-agent' or undefined

// Get the base URL
const baseUrl = client.getBaseUrl(); // 'https://api.clawmail.to'

Create Client for Different Agent

Use forAgent() to quickly create a client for a different agent:

const supportClient = client.forAgent('support-agent', 'support-api-key');
const salesClient = client.forAgent('sales-agent', 'sales-api-key');

// Each client operates independently
await supportClient.send.email({ ... });
await salesClient.send.email({ ... });

Update Configuration

Use withOptions() to create a new client with modified options:

// After rotating API key
const newKeyResult = await client.agents.rotateKey();
const newClient = client.withOptions({
  apiKey: newKeyResult.apiKey
});

// Add custom headers
const tracedClient = client.withOptions({
  headers: { 'X-Trace-ID': 'abc123' }
});

TypeScript Types

Import types for full type safety:

import type {
  ClawMailClientOptions,
  Agent,
  Email,
  SendEmailOptions,
  PaginatedResponse,
  VerificationStartResponse,
  VerificationCompleteResponse,
  VerificationStatusResponse
} from '@clawmail/client';

// Typed function
async function processEmails(client: ClawMailClient): Promise<void> {
  const inbox: PaginatedResponse<Email> = await client.emails.list();

  for (const email of inbox.data) {
    console.log(email.subject); // TypeScript knows this is string
  }
}

Custom Fetch

Provide a custom fetch function for logging, retries, or testing:

const client = new ClawMailClient({
  baseUrl: 'https://api.clawmail.to',
  apiKey: 'cmail_abc123...',
  agentId: 'my-agent',
  fetch: async (url, init) => {
    console.log(`[API] ${init?.method || 'GET'} ${url}`);
    const start = Date.now();
    const response = await globalThis.fetch(url, init);
    console.log(`[API] ${response.status} in ${Date.now() - start}ms`);
    return response;
  }
});

Environment Variables

A common pattern is to use environment variables:

const client = new ClawMailClient({
  baseUrl: process.env.CLAWMAIL_BASE_URL!,
  apiKey: process.env.CLAWMAIL_API_KEY!,
  agentId: process.env.CLAWMAIL_AGENT_ID!
});

Never commit API keys to source control. Use environment variables or a secrets manager.

Edge Runtime Support

The client works in edge runtimes like Cloudflare Workers:

// Cloudflare Worker
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const client = new ClawMailClient({
      baseUrl: env.CLAWMAIL_BASE_URL,
      apiKey: env.CLAWMAIL_API_KEY,
      agentId: env.CLAWMAIL_AGENT_ID
    });

    const inbox = await client.emails.list({ folder: 'inbox' });
    return Response.json(inbox);
  }
};

Installation & Setup