cakemail-mcp-server
Version:
Enterprise MCP server for Cakemail API integration with Claude AI - includes comprehensive template management, list management, sub-account management, BEEeditor visual email design, and advanced analytics
180 lines (149 loc) • 6.22 kB
Markdown
# Sub-Account Export Capacity Feature
## Overview
I have successfully added comprehensive export capacity functionality to your sub-account management system in the cakemail-mcp-server. This feature allows users to export all sub-account data in both CSV and JSON formats with extensive customization options.
## What Was Implemented
### 1. New Export Handler (`handleExportSubAccounts`)
- **Location**: `src/handlers/sub-accounts.ts`
- **Functionality**:
- Exports sub-accounts data in CSV or JSON format
- Supports filtering by status, partner account ID
- Includes comprehensive data collection across multiple pages
- Provides detailed statistics and previews
### 2. Enhanced SubAccountApi Class
- **Location**: `src/api/sub-account-api.ts`
- **New Method**: `exportSubAccountsData()`
- **Features**:
- Automatically paginates through all sub-accounts
- Processes accounts for export with comprehensive information
- Supports filtering and data inclusion options
### 3. Updated Handler Registry
- **Location**: `src/handlers/index.ts`
- **Addition**: Added `cakemail_export_sub_accounts` to the handler registry
- **Integration**: Properly integrated with existing handler system
### 4. Tool Configuration (Already Existed)
- **Location**: `src/config/sub-account-tools.ts`
- **Tool**: `cakemail_export_sub_accounts` was already defined with comprehensive parameters
## Export Capabilities
### Supported Formats
- **CSV**: Comma-separated values with proper escaping
- **JSON**: Structured JSON with metadata and export information
### Data Included
- **Basic Information**: ID, name, status, lineage, partner flag, creation/expiry dates
- **Owner Details** (optional): Owner name and email
- **Usage Statistics** (optional): Email limits, remaining emails, feature flags
- **Contact Statistics** (placeholder): Total contacts, active contacts, lists count
### Filtering Options
- **Status Filter**: pending, active, suspended, inactive
- **Partner Account ID**: Filter by specific partner account
- **Recursive**: Include sub-accounts of sub-accounts
### Export Features
- **Pagination Handling**: Automatically collects data from all pages
- **Custom Filenames**: Support for custom export filenames
- **Statistics**: Detailed breakdown by status, partner accounts, etc.
- **Preview**: Shows first 3 records in the response
- **Full Data**: Complete export data included in response
## Usage Example
### Basic CSV Export
```json
{
"name": "cakemail_export_sub_accounts",
"arguments": {
"format": "csv"
}
}
```
### Advanced Export with Filters
```json
{
"name": "cakemail_export_sub_accounts",
"arguments": {
"format": "json",
"status_filter": "active",
"include_usage_stats": true,
"include_owner_details": true,
"recursive": true,
"filename": "active-subaccounts-2025"
}
}
```
## Response Structure
The export tool returns:
- **Export Statistics**: Total accounts, breakdown by status, partner accounts count
- **Export Options**: What data was included/excluded
- **Preview**: First 3 records for verification
- **Full Export Data**: Complete CSV or JSON content ready for use
### Example CSV Output
```csv
"id","name","status","lineage","is_partner","created_on","expires_on","owner_name","owner_email","emails_per_month"
"123","Company A","active","root.123",false,"2024-01-15","2025-01-15","John Doe","john@example.com",5000
"124","Company B","suspended","root.124",true,"2024-02-01","2025-02-01","Jane Smith","jane@example.com",10000
```
### Example JSON Output
```json
{
"export_info": {
"generated_at": "2025-01-15T10:30:00Z",
"total_accounts": 2,
"filters": {
"status_filter": "active",
"partner_account_id": null,
"recursive": false
},
"includes": {
"usage_stats": true,
"contact_counts": false,
"owner_details": true
}
},
"accounts": [
{
"id": "123",
"name": "Company A",
"status": "active",
"lineage": "root.123",
"is_partner": false,
"created_on": "2024-01-15",
"expires_on": "2025-01-15",
"owner_name": "John Doe",
"owner_email": "john@example.com",
"emails_per_month": 5000,
"emails_remaining": 4500,
"use_automations": true
}
]
}
```
## Error Handling
The export functionality includes comprehensive error handling:
- **Invalid Format**: Returns error for unsupported formats
- **No Data**: Graceful handling when no sub-accounts match criteria
- **API Errors**: Proper error propagation from underlying API calls
- **Validation**: Input parameter validation with clear error messages
## Integration Notes
1. **Existing API Compatibility**: Uses existing `listSubAccounts` method, fully compatible with current API structure
2. **Pagination**: Automatically handles pagination to export all data
3. **Performance**: Optimized to fetch data in batches of 100 records
4. **Memory Efficient**: Processes data incrementally rather than loading everything at once
## Technical Implementation Details
### Files Modified
1. `src/handlers/sub-accounts.ts` - Added `handleExportSubAccounts` function
2. `src/handlers/index.ts` - Added handler to registry and imports
3. `src/api/sub-account-api.ts` - Added `exportSubAccountsData` method
### Dependencies
- No new dependencies added
- Uses existing TypeScript types and error handling
- Leverages current API infrastructure
## Testing Recommendations
1. **Basic Export Test**: Export with default parameters
2. **Format Testing**: Test both CSV and JSON formats
3. **Filter Testing**: Test with different status filters and partner IDs
4. **Large Dataset**: Test with accounts that require pagination
5. **Error Cases**: Test with invalid parameters and no data scenarios
## Future Enhancements
Potential areas for expansion:
1. **Contact Count Integration**: Real contact counting by integrating with Lists API
2. **Additional Formats**: Support for Excel, XML, or other formats
3. **Scheduled Exports**: Automatic periodic exports
4. **Export History**: Track and manage previous exports
5. **Custom Fields**: Allow selection of specific fields to export
The export functionality is now fully integrated and ready for use!