Mail API

The Mail API provides comprehensive messaging and collaboration capabilities, enabling agents to communicate through threads, manage messages, and coordinate file access during collaborative work.

Overview

The mail module enables you to:

• Agent Communication: Register and manage agents for inter-agent messaging
• Thread Management: Create and manage conversation threads
• Message Exchange: Send, receive, and search messages
• Collaboration: Coordinate file access with reservation system
• Status Tracking: Monitor message and thread status

Quick Start Example

import codebolt from '@codebolt/codeboltjs';

// Wait for connection
await codebolt.waitForReady();

// Register an agent
await codebolt.mail.registerAgent({
  agentId: 'agent-001',
  name: 'Developer Agent',
  capabilities: ['code-review', 'debugging']
});

// Create a conversation thread
const thread = await codebolt.mail.createThread({
  subject: 'Code Review: Authentication Module',
  participants: ['agent-001', 'agent-002'],
  type: 'agent-to-agent',
  metadata: {
    project: 'auth-system',
    priority: 'high'
  }
});

// Send a message
await codebolt.mail.sendMessage({
  threadId: thread.thread.id,
  content: 'Please review the authentication changes',
  senderId: 'agent-001'
});

// Fetch inbox for new messages
const inbox = await codebolt.mail.fetchInbox({
  agentId: 'agent-002',
  limit: 10
});

console.log('New messages:', inbox.messages);

Response Structure

All mail API functions return responses with a consistent structure:

{
  success: boolean;
  data?: any;
  error?: string;
  timestamp?: string;
}

Common Use Cases

Agent-to-Agent Communication

// Register multiple agents
await codebolt.mail.registerAgent({
  agentId: 'frontend-agent',
  name: 'Frontend Developer',
  capabilities: ['ui', 'react']
});

await codebolt.mail.registerAgent({
  agentId: 'backend-agent',
  name: 'Backend Developer',
  capabilities: ['api', 'database']
});

// Create a thread for collaboration
const thread = await codebolt.mail.createThread({
  subject: 'API Integration Discussion',
  participants: ['frontend-agent', 'backend-agent'],
  type: 'agent-to-agent'
});

// Exchange messages
await codebolt.mail.sendMessage({
  threadId: thread.thread.id,
  content: 'I need the new API endpoints for user management',
  senderId: 'frontend-agent'
});

File Collaboration with Reservations

// Reserve files for exclusive access
await codebolt.mail.reserveFiles({
  agentId: 'agent-001',
  files: ['src/auth/login.ts', 'src/auth/session.ts'],
  threadId: 'thread-123'
});

// Work on the files...

// Release when done
await codebolt.mail.releaseFiles({
  agentId: 'agent-001',
  files: ['src/auth/login.ts', 'src/auth/session.ts']
});

Message Search and Retrieval

// Search for specific messages
const results = await codebolt.mail.search({
  query: 'authentication bug',
  threadId: 'thread-123',
  limit: 20
});

// Get thread summary
const summary = await codebolt.mail.summarizeThread({
  threadId: 'thread-123'
});

console.log('Thread summary:', summary.summary);

• registerAgent - Registers an agent with the mail system to enable sending and receiving messages.
• listAgents - Lists all registered agents in the mail system.
• getAgent - Retrieves details about a specific registered agent.
• createThread - Creates a new mail thread for conversation between agents or users.
• findOrCreateThread - Finds an existing thread or creates a new one based on participants.
• listThreads - Lists all mail threads with optional filtering and pagination.
• getThread - Retrieves detailed information about a specific mail thread.
• updateThreadStatus - Updates the status of a mail thread (open, closed, archived).
• archiveThread - Archives a mail thread to remove it from active view.
• fetchInbox - Fetches messages from the agent's inbox.
• sendMessage - Sends a message to a specific mail thread.
• replyMessage - Replies to an existing message in a thread.
• getMessage - Retrieves a specific message by its ID.
• getMessages - Retrieves all messages from a specific mail thread.
• markRead - Marks a message or thread as read.
• acknowledge - Acknowledges receipt of a message.
• search - Searches for messages matching specific criteria.
• summarizeThread - Generates a summary of a mail thread's conversation.
• reserveFiles - Reserves files for exclusive access during collaboration.
• releaseFiles - Releases file reservations after collaboration is complete.
• forceReserveFiles - Forcefully reserves files, overriding existing reservations.
• listReservations - Lists all active file reservations.
• checkConflicts - Checks for potential conflicts in file reservations.