Move Email to Archive Skill

⚠️ IMPORTANT: Claude Context Required

This skill ONLY works when executed within Claude Agent context (bassi, Claude Code, or other Claude Agent environments).

• •✅ Works: Inside a Claude agent that has MS365 authentication
• •❌ Does NOT work: As a standalone Python script outside Claude context
• •❌ Does NOT work: Without MS365 authentication already provided by Claude

The Python script (scripts/move_to_archive.py) is a parameter preparation tool, not a standalone email mover. It prepares parameters that Claude's tool system then executes.

Purpose

Move one specific email message to the Archive folder in Microsoft 365 Mail with a clean, context-efficient interface.

When to Use

• •Moving individual emails to Archive (spam, no-TODO items, notifications)
• •Bulk archive operations (chain multiple calls efficiently)
• •Any workflow requiring reliable, one-at-a-time email archival
• •When the main context should not be polluted by full email move operation details

How to Use This Skill

Quick Start: Direct API Call (Within Claude Context)

For a single email move, use the MS365 mail API directly with these parameters:

Function: mcp__ms365__move-mail-message

Required Parameters:

• •messageId: The unique message ID of the email to move (string)
• •body: JSON object with destination folder ID

Optional Parameter:

• •Archive Folder ID: Use default from references/archive_config.md unless overriding

Example Call Structure

# Minimum parameters needed (within Claude agent context)
messageId = "AAMkADA4YjhhZDYwLWZiMWYtNDVkMy1hNjE3LWI3YzRlMzAwNGE0MgBGAAA..."
archive_folder_id = "AQMkADA4YjhhZDYwLWZiMWYtNDVkMy1hNjE3LWI3YzRlMzAwADRhNDIALgAAA-cCSmDe9C5Ai1IxFty3vKgBACIai-AjXXpFuMeLL-NexTAAAAIBVAAAAA=="

response = mcp__ms365__move-mail-message(
    messageId=messageId,
    body={"DestinationId": archive_folder_id}
)

Key Success Pattern: One Email at a Time

Critical Finding: Moving emails individually (one per call) works reliably. Batch operations cause ErrorInvalidIdMalformed errors. Always move ONE email per operation call.

Python Script Approach (Prepares Parameters for Claude)

Use scripts/move_to_archive.py to prepare parameters. This script:

• •Handles default Archive folder ID lookup
• •Validates messageId parameter format
• •Returns JSON with parameters ready for Claude's API execution
• •Can be chained in loops without context pollution

What it does: Returns the parameters Claude needs to execute the move What it does NOT do: Move emails directly (requires Claude context)

Usage:

python scripts/move_to_archive.py --message-id "AAMkADA4YjhhZDYwLWZiMWYtNDVkMy1h..." [--archive-id "custom-id"]

Output:

{
  "status": "ready",
  "operation": {
    "api_function": "mcp__ms365__move-mail-message",
    "parameters": {
      "messageId": "AAMkADA4YjhhZDYwLWZiMWYtNDVkMy1h...",
      "body": {
        "DestinationId": "AQMkADA4YjhhZDYwLWZi..."
      }
    }
  }
}

Reference Materials

• •API Documentation: See references/api_docs.md for full MS365 Mail API parameter details
• •Archive Configuration: See references/archive_config.md for Archive folder ID and defaults
• •Archive Folder ID Default: AQMkADA4YjhhZDYwLWZiMWYtNDVkMy1hNjE3LWI3YzRlMzAwADRhNDIALgAAA-cCSmDe9C5Ai1IxFty3vKgBACIai-AjXXpFuMeLL-NexTAAAAIBVAAAAA==

Expected Response

Success response includes:

• •id: Email ID (confirming which email was moved)
• •parentFolderId: Archive folder ID (confirming destination)
• •subject: Email subject (for reference)
• •receivedDateTime: When email was received

Indicates Success: parentFolderId equals the Archive folder ID

Important Notes

1. •One at a time: Always move ONE email per operation call
2. •Message ID format: Use the full message ID from the email list response
3. •No batch operations: Do not attempt to move multiple emails in a single call
4. •Claude context required: All operations must happen within Claude agent context
5. •Context efficiency: This skill is designed to keep operations lean and not blow up context window

Troubleshooting

Bulk Operations: Using Sub-Agents

For archiving multiple emails without polluting context:

1. •Prepare list of message IDs to archive
2. •Launch a sub-agent using the bulk archive agent template
3. •Sub-agent iterates through each ID and calls the move operation
4. •Sub-agent returns summary to main context (one-line result, not 50+ lines)

Sub-Agent Usage

See .claude/agents/bulk-archive-agent.md and .claude/agents/BULK_ARCHIVE_TASK_TEMPLATE.md for:

• •Complete sub-agent architecture
• •Task prompt template ready to copy/paste
• •Examples of bulk archive workflows
• •Error handling patterns

Quick Example:

Main Context: "Archive 50 emails"
   → Launch bulk-archive sub-agent with message IDs
   → Sub-agent moves silently (one at a time)
   → Returns: "✅ Archived 48 emails. ❌ 2 failed."
Result: Clean context, 1 summary line instead of 50 confirmations

Architecture Overview

Single Email Move (use skill directly):
  User request → Direct API call → Archive → Done (inline, context stays clean)

Bulk Email Move (use sub-agent):
  User request → Identify emails → Launch sub-agent → Sub-agent archives silently → Summary to context
                                                  ↓
                                          (50+ operations happen here,
                                           context stays clean)