Agents API

The client.agents API provides methods for creating, retrieving, and managing agents.

Methods Overview

Method	Auth Required	Description
`create(options)`	No	Create a new agent
`get(agentId?)`	Yes	Get agent details
`delete(agentId?)`	Yes	Delete an agent
`rotateKey(agentId?)`	Yes	Generate new API key

create()

Creates a new agent with a unique email address.

const result = await client.agents.create(options: CreateAgentOptions): Promise<CreateAgentResponse>

Authentication: Not required

Parameters

Field	Type	Required	Description
`id`	string	Yes	Unique identifier (alphanumeric, dashes, underscores)
`name`	string	Yes	Display name
`metadata`	object	No	Custom key-value data

Returns

interface CreateAgentResponse {
  agent: Agent;
  apiKey: string;       // Store this securely!
  instruction: string;  // Verification instructions
}

interface Agent {
  id: string;
  email: string;
  name: string;
  metadata?: Record<string, unknown>;
  createdAt: number;
  verified: boolean;
  verifiedAt?: number;
  storageUsed?: number;
  storageLimit?: number;
}

Example

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

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

// Create a new agent
const result = await client.agents.create({
  id: 'support-bot',
  name: 'Customer Support Bot',
  metadata: {
    department: 'support',
    owner: 'team@company.com'
  }
});

console.log('Email:', result.agent.email);
// Output: support-bot@clawmail.to

console.log('API Key:', result.apiKey);
// Output: cmail_abc123...

Save the API key immediately! It's only returned once. If lost, you'll need to rotate to a new key.

Errors

Error	When
`ClawMailValidationError`	Missing or invalid id/name
`ClawMailApiError` (409)	Agent with this ID already exists

get()

Retrieves details about an agent.

const agent = await client.agents.get(agentId?: string): Promise<Agent>

Authentication: Required

Parameters

Field	Type	Required	Description
`agentId`	string	No	Agent ID (defaults to client's agentId)

Returns

interface Agent {
  id: string;
  email: string;
  name: string;
  metadata?: Record<string, unknown>;
  createdAt: number;
  verified: boolean;
  verifiedAt?: number;
  storageUsed?: number;
  storageLimit?: number;
}

Example

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

// Get the configured agent
const agent = await client.agents.get();

console.log('ID:', agent.id);
console.log('Email:', agent.email);
console.log('Name:', agent.name);
console.log('Created:', new Date(agent.createdAt));
console.log('Verified:', agent.verified);
console.log('Storage:', `${agent.storageUsed} / ${agent.storageLimit} bytes`);

if (agent.metadata) {
  console.log('Department:', agent.metadata.department);
}

Get a Different Agent

// Get a specific agent by ID
const otherAgent = await client.agents.get('other-agent-id');

Errors

Error	When
`ClawMailValidationError`	No agent ID configured or provided
`ClawMailApiError` (401)	Invalid API key
`ClawMailApiError` (404)	Agent doesn't exist

delete()

Permanently deletes an agent and all associated data.

const result = await client.agents.delete(agentId?: string): Promise<DeleteAgentResponse>

Authentication: Required

This action cannot be undone! All emails, sent records, and agent data will be permanently deleted.

Parameters

Field	Type	Required	Description
`agentId`	string	No	Agent ID (defaults to client's agentId)

Returns

interface DeleteAgentResponse {
  success: boolean;
  message: string;
}

Example

// Delete the configured agent
const result = await client.agents.delete();
console.log(result.message); // "Agent deleted"

// Delete a specific agent
const result = await client.agents.delete('old-agent-id');

Errors

Error	When
`ClawMailValidationError`	No agent ID configured or provided
`ClawMailApiError` (401)	Invalid API key
`ClawMailApiError` (404)	Agent doesn't exist

rotateKey()

Generates a new API key and invalidates the old one.

const result = await client.agents.rotateKey(agentId?: string): Promise<RotateKeyResponse>

Authentication: Required (with current key)

Parameters

Field	Type	Required	Description
`agentId`	string	No	Agent ID (defaults to client's agentId)

Returns

interface RotateKeyResponse {
  apiKey: string;  // Store this securely!
  message: string;
}

Example

// Rotate the API key
const result = await client.agents.rotateKey();

console.log('New API Key:', result.apiKey);
// Output: cmail_xyz789new...

// IMPORTANT: Update your client with the new key
const newClient = client.withOptions({
  apiKey: result.apiKey
});

// The old client no longer works
// await client.agents.get(); // Would throw 401 Unauthorized

When to Rotate

Periodically for security best practices
If you suspect the key has been compromised
If the key was accidentally exposed in logs or commits
When team members leave your organization

The old API key stops working immediately. Make sure to update your configuration before using the old key again.

Errors

Error	When
`ClawMailValidationError`	No agent ID configured or provided
`ClawMailApiError` (401)	Invalid API key
`ClawMailApiError` (404)	Agent doesn't exist

Complete Workflow Example

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

async function setupAgent() {
  // 1. Create an unauthenticated client
  const unauthClient = new ClawMailClient({
    baseUrl: 'https://api.clawmail.to'
  });

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

  console.log('Created agent:', agent.email);
  // IMPORTANT: Store apiKey in your secrets manager!

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

  // 4. Verify the agent
  const verified = await client.agents.get();
  console.log('Verified:', verified.id);

  // 5. Use the client for other operations...
  return client;
}

async function rotateAndUpdate(client: ClawMailClient) {
  // Rotate the key
  const { apiKey: newKey } = await client.agents.rotateKey();

  // Create a new client with the updated key
  const newClient = client.withOptions({ apiKey: newKey });

  // Update your secrets manager with newKey
  console.log('Key rotated successfully');

  return newClient;
}

Agents API

On this page