msexchange-mcp/FOLDER_MANAGEMENT_GUIDE.md

MCP server for Microsoft Exchange/Outlook email operations via Microsoft Graph API

# Folder Management Guide

## New Folder Management Tools (v1.2.0)

The Exchange MCP now includes comprehensive folder management capabilities to help organize your emails effectively.

## Available Tools

### 1. `create_folder` - Create Individual Folders

Create a new mail folder in your mailbox.

**Parameters:**
- `user_id`: Email address or user ID
- `folder_name`: Name of the new folder
- `parent_folder_id`: (Optional) Parent folder ID for subfolder creation

**Examples:**
```bash
# Create a root-level folder
create_folder --user_id "olivier@surge.management" --folder_name "Projects"

# Create a subfolder under existing folder
create_folder --user_id "olivier@surge.management" --folder_name "Client A" --parent_folder_id "AAMkAGVm..."
```

### 2. `setup_organization_folders` - Quick Organization Setup

Create predefined sets of organizational folders for different use cases.

**Parameters:**
- `user_id`: Email address or user ID  
- `folder_set`: Predefined set (business, personal, minimal, custom)
- `custom_folders`: Array of folder names for custom set
- `parent_folder_id`: (Optional) Parent folder for all new folders

## Predefined Folder Sets

### 📈 Business Set (Default)
Perfect for professional email management:
- **Action Required** - Emails needing immediate attention
- **Follow Up** - Items to revisit later
- **Projects** - Project-related communications
- **Clients** - Client correspondence
- **Financial** - Invoices, expenses, financial documents
- **Legal** - Contracts, legal documents
- **HR** - Human resources, personnel matters
- **Completed** - Finished tasks and resolved issues
- **Archive** - Long-term storage

### 👤 Personal Set
Ideal for personal email organization:
- **Action Required** - Personal tasks needing attention
- **Family** - Family communications
- **Friends** - Social correspondence
- **Bills & Finance** - Personal financial matters
- **Shopping** - Orders, receipts, shopping-related
- **Travel** - Bookings, itineraries, travel plans
- **Health** - Medical, insurance, health-related
- **Archive** - Personal long-term storage

### ⚡ Minimal Set
Simple organization for streamlined workflows:
- **Action Required** - Immediate attention items
- **Follow Up** - Items to revisit
- **Archive** - Completed/reference items

### 🛠️ Custom Set
Define your own folder structure:
```bash
setup_organization_folders --user_id "user@example.com" --folder_set "custom" --custom_folders '["Marketing", "Development", "Support", "Admin"]'
```

## Usage Examples

### Quick Business Setup
```bash
# Set up complete business organization structure
setup_organization_folders --user_id "olivier@surge.management" --folder_set "business"
```

### Personal Email Organization
```bash
# Set up personal email structure
setup_organization_folders --user_id "personal@example.com" --folder_set "personal"
```

### Custom Project Folders
```bash
# Create custom folder structure for specific needs
setup_organization_folders --user_id "user@example.com" --folder_set "custom" --custom_folders '["Urgent", "This Week", "Next Week", "Someday", "Reference"]'
```

### Individual Folder Creation
```bash
# Create specific folders as needed
create_folder --user_id "user@example.com" --folder_name "Q1 2024 Planning"
create_folder --user_id "user@example.com" --folder_name "Conference Prep"
```

## Best Practices

### 📋 Email Organization Strategy

1. **Start with Action Required**
   - Move emails needing immediate action here first
   - Review this folder daily
   - Keep it as empty as possible

2. **Use Projects/Clients for Context**
   - Group related emails together
   - Create subfolders for large projects
   - Archive completed project folders

3. **Regular Maintenance**
   - Weekly review of Follow Up folder
   - Monthly archive old completed items
   - Quarterly cleanup of unused folders

### 🏷️ Combine with Categories

Folders work best when combined with email categories:
```bash
# Example workflow
1. Move email to "Projects" folder
2. Add category "High Priority" for urgency
3. Add category "Client-A" for filtering
```

### 📁 Folder Hierarchy Tips

- Keep folder structure shallow (max 2-3 levels deep)
- Use clear, descriptive names
- Consider your workflow when designing structure
- Start simple and expand as needed

## Integration with Existing Tools

### Moving Emails to New Folders
```bash
# First create the folder
create_folder --user_id "user@example.com" --folder_name "Q1 Planning"

# Then list folders to get the ID
list_folders --user_id "user@example.com"

# Move emails to the new folder
move_email --user_id "user@example.com" --message_id "email-id" --destination_folder_id "folder-id"
```

### Category + Folder Organization
```bash
# Organize with both folders and categories
move_email --user_id "user@example.com" --message_id "email-id" --destination_folder_id "projects-folder-id"
update_email_categories --user_id "user@example.com" --message_id "email-id" --categories '["High Priority", "Q1"]'
```

## Response Format

Both tools return detailed information about created folders:

```json
{
  "success": true,
  "summary": {
    "folderSet": "business",
    "totalAttempted": 9,
    "successfullyCreated": 9,
    "errors": 0
  },
  "createdFolders": [
    {
      "name": "Action Required",
      "id": "AAMkAGVm...",
      "status": "created"
    }
  ],
  "organizationTips": [
    "Use 'Action Required' for emails that need immediate attention",
    "Move completed items to 'Archive' to keep folders organized"
  ]
}
```

## Error Handling

The tools handle common issues gracefully:
- **Duplicate folder names**: Will show specific error for existing folders
- **Rate limiting**: Automatic delays between folder creation
- **Permission issues**: Clear error messages for access problems
- **Partial failures**: Continue creating other folders if some fail

## Migration Strategy

### From Existing Email Setup
1. **Audit current folders**: Use `list_folders` to see existing structure
2. **Plan new structure**: Choose appropriate folder set
3. **Create new folders**: Use `setup_organization_folders`
4. **Gradually migrate**: Move emails to new structure over time
5. **Clean up**: Remove old unused folders manually in Outlook

### Scaling Your Organization
1. **Start minimal**: Begin with the minimal set
2. **Add as needed**: Create specific folders with `create_folder`
3. **Regular review**: Assess folder usage monthly
4. **Archive old projects**: Move completed work to archive

## Conclusion

The new folder management tools provide:
✅ **Quick setup** of professional organization structures
✅ **Flexible creation** of custom folders
✅ **Rate-limited operations** to avoid API issues  
✅ **Comprehensive error handling** for reliable operation
✅ **Integration** with existing email management tools

Use these tools to create a structured, efficient email organization system that scales with your needs!