Mail Folder Rationalization and Historical Migration Specification

1. Purpose

This document defines how the Inbox Agent project should inventory, rationalize, map, migrate, and reconcile historical email across the user's current mail estate.

The goals are:

2. Current Mail Estate

2.1 Personal Microsoft Mailbox

jskoch@msn.com

Purpose:

Target role:

PRIMARY PERSONAL MAILBOX

2.2 Professional Microsoft Mailbox

jason@jasonkoch.io

Purpose:

Platform:

Microsoft 365

Tenant:

jasonkoch13.onmicrosoft.com

Target role:

PRIMARY PROFESSIONAL MAILBOX

2.3 Project / AI Alias

jason@jasonkoch.ai

This is not a separate physical mailbox.

It is an alias associated with:

jason@jasonkoch.io

Purpose:

The system must preserve the original recipient address so mail received through the alias can be distinguished from mail sent directly to jason@jasonkoch.io.

2.4 Commercial Gmail Mailbox

Jason.s.koch@gmail.com

Purpose:

Target role:

COMMERCIAL / LOW-VALUE MAILBOX

This mailbox is intentionally allowed to contain higher volumes of low-value mail.

It should not contribute equally to user workload metrics.

2.5 System / Service Gmail Mailbox

platypus.software.dev@gmail.com

Purpose:

Target role:

SYSTEM / SERVICE MAILBOX

This mailbox should be optimized for exception detection rather than ordinary inbox review.

2.6 Active iCloud Account

jskoch67@icloud.com

Current roles:

Target role:

APPLE INFRASTRUCTURE ACCOUNT

Mail should not remain a major long-term organizational store unless required.

Shared calendars and contacts remain on iCloud.

2.7 Legacy iCloud Account

Jason.s.koch@icloud.com

Current role:

LEGACY APPLE ACCOUNT

Target:

INVENTORY
PRESERVE REQUIRED CONTENT
MIGRATE USEFUL MAIL IF APPROPRIATE
RETIRE FROM ACTIVE MAIL USE

Retirement of the email function must not assume that the underlying Apple account can be deleted.

3. Folder Rationalization Principle

The target model is:

FEWER PHYSICAL FOLDERS
+
MORE SEMANTIC METADATA
+
CROSS-MAILBOX VIEWS

The system should not recreate the existing folder mess under a new provider.

The project should assume that historical folder structures contain:

4. Discovery Must Be Read-Only

The first folder discovery operation must not:

Discovery produces an inventory only.

5. Folder Inventory Schema

Every folder discovered should be represented as a record.

Required fields:

folder_id
mailbox_id
provider
folder_name
folder_path
parent_folder_id
folder_type
is_system_folder
message_count
unread_count
oldest_message_date
newest_message_date
estimated_size
child_folder_count

Recommended analysis fields:

likely_semantic_role
likely_duplicate_group
migration_candidate
confidence
notes

6. System Folders

Provider-managed system folders must be identified separately.

Examples may include:

Inbox
Sent
Drafts
Deleted Items
Junk
Spam
Archive
Outbox
Conversation History

System folders should not be treated as ordinary user-created folders.

The system must not rename or delete required provider system folders.

7. Folder Classification

Every discovered user-created folder should receive a preliminary classification.

Possible values:

ACTIVE_ORGANIZATION
LEGACY_ORGANIZATION
REFERENCE
ARCHIVE
AUTOMATED_MAIL
COMMERCIAL
SYSTEM
PROJECT
PERSONAL
FINANCIAL
TRAVEL
MIXED
EMPTY
UNKNOWN

This classification is analytical, not necessarily the final destination.

8. Folder Disposition Model

Every existing folder should eventually receive one migration disposition.

Valid dispositions:

KEEP
MERGE
RENAME
ARCHIVE_AS_IS
CONVERT_TO_VIEW
MOVE_CONTENT_ONLY
DELETE_EMPTY
REVIEW

KEEP

The folder remains physically meaningful.

MERGE

Its contents move into another physical folder.

RENAME

The concept remains valid but should use standardized naming.

ARCHIVE_AS_IS

The folder remains only as historical archive structure.

CONVERT_TO_VIEW

The folder concept should disappear physically and be represented by metadata or a virtual view.

MOVE_CONTENT_ONLY

Messages are moved, but the old folder itself has no future role.

DELETE_EMPTY

Folder contains no messages and may be removed after review.

REVIEW

No safe automated disposition can yet be determined.

9. Duplicate Folder Detection

Folder duplication should be detected using more than exact name matching.

Potential duplicate examples:

Receipt
Receipts
Purchases
Orders
Shopping

Dev
Development
GitHub
Programming

Saved
Reference
Important
Keep

Travel
Trips
Vacation
Flights
Hotels

Signals:

The agent should form candidate semantic groups rather than automatically merge folders.

10. Semantic Folder Groups

The system may generate a structure such as:

Candidate Group: RECEIPTS

Folders:
- iCloud/Receipts
- MSN/Purchases
- Gmail/Orders

Recommendation:
Merge content into semantic category RECEIPT.
Do not necessarily create a physical Receipts folder unless approved.

This distinction is important.

A duplicate group does not automatically imply a target folder.

11. Folder Usage Analysis

Each folder should be analyzed for actual use.

Useful metrics include:

Messages added in last 30 days
Messages added in last 90 days
Messages added in last year
Percentage unread
Percentage automated
Percentage human correspondence
Percentage older than 5 years
Dominant senders
Dominant classifications

A folder that has not received a message in eight years may be historical even if it sounds important.

12. Mixed Folders

Some folders may contain unrelated content.

Example:

Saved

may contain:

Such folders should not be mapped wholesale based on the folder name.

Instead:

CLASSIFY MESSAGES
THEN MIGRATE BY MESSAGE SEMANTICS

This is an important exception to simple folder-to-folder migration.

13. Target Physical Folder Strategy

The target physical structure should remain intentionally minimal.

Initial candidate:

Inbox
Sent
Drafts
Archive

Optional action-oriented folders may exist if provider/client limitations make them operationally useful:

Action
Waiting

However, the preferred design is that concepts such as:

Action
Waiting
Professional
Family
Finance
Travel
Development
Receipts
Read Later

are represented primarily through metadata and views.

Final folder decisions should occur after discovery.

14. Archive Strategy

Archive should mean:

Retained but not currently requiring attention.

Archive should not attempt to encode topic hierarchy.

A centralized archive can contain messages across many semantic categories.

The Inbox Agent must make archived mail easily discoverable through search, metadata, and views.

15. Historical Folder Preservation

Historical folder hierarchy may contain useful context.

The migration process should therefore preserve original folder information as metadata even if the physical folder no longer exists.

For every migrated message:

source_provider
source_mailbox
source_folder_id
source_folder_path
migration_timestamp

Example:

source_provider = iCloud
source_mailbox = jskoch67@icloud.com
source_folder_path = Personal/Travel/Europe/2018

The physical destination might simply be:

Archive

but the original path remains queryable.

16. Canonical Mail Storage

The preferred canonical platform is Microsoft where practical.

This does not necessarily mean every active mailbox must physically merge into one mailbox.

The following should remain logically distinct:

PERSONAL
jskoch@msn.com

PROFESSIONAL
jason@jasonkoch.io

PROJECT ALIAS
jason@jasonkoch.ai

Historical iCloud mail may be migrated into the most appropriate Microsoft mailbox based on recipient identity and message context.

17. Historical iCloud Migration

Historical mail from:

jskoch67@icloud.com
Jason.s.koch@icloud.com

must be inventoried before migration.

Migration analysis should determine:

Total message count
Total estimated size
Folder count
Oldest message
Newest message
Attachment volume
Duplicate rate
Messages already forwarded to MSN
Messages belonging to another identity

The existence of forwarding creates a significant duplicate risk.

18. Forwarding Duplicate Risk

Because:

jskoch67@icloud.com
→ forwards to jskoch@msn.com

some messages may exist in both mailboxes.

Migration must not assume every iCloud message is unique.

Duplicate detection should preferentially use:

Internet Message-ID

where available.

Secondary matching may include:

Sender
Recipient
Subject
Sent timestamp
Received timestamp
Normalized body hash
Attachment metadata

19. Duplicate States

Messages should have a duplicate analysis status:

UNIQUE
LIKELY_DUPLICATE
CONFIRMED_DUPLICATE
CONFLICT
UNKNOWN

Duplicates should not be permanently deleted during migration.

20. Duplicate Canonicalization

When duplicates exist, the system should select a canonical copy based on rules such as:

1. Preserve the copy in the target canonical mailbox when possible.
2. Prefer the message with complete headers.
3. Prefer the message with intact attachments.
4. Preserve the copy with richer conversation context.
5. Retain provenance for all detected copies.

Where uncertainty exists, retain both and flag for later cleanup.

21. Migration Destination Rules

Historical messages should be routed based on the identity they logically belong to.

Examples:

Personal correspondence
→ jskoch@msn.com

Professional correspondence
→ jason@jasonkoch.io

Project / AI correspondence
→ jason@jasonkoch.io
   recipient identity preserved as jason@jasonkoch.ai when applicable

Commercial correspondence
→ potentially retain in Gmail or archive separately

System/service correspondence
→ platypus.software.dev@gmail.com where relevant

Migration should not move mail across identities merely for tidiness unless the semantic mapping is clear.

22. Migration Batches

Migration should operate in discrete batches.

Example:

Batch 001
Source:
jskoch67@icloud.com

Source Folder:
Receipts

Date Range:
2018-01-01 through 2020-12-31

Destination:
jskoch@msn.com / Archive

Each batch receives a unique migration run identifier.

23. Dry Run

Every migration batch should support dry-run mode.

Dry run output should include:

Messages selected
Messages eligible
Likely duplicates
Conflicts
Messages skipped
Estimated data volume
Target mailbox
Target folder
Classification summary

No mailbox mutation occurs during dry run.

24. Pilot Migration

Before bulk migration, select a representative pilot.

Pilot should include:

Pilot validation should verify:

Sender preserved
Recipients preserved
Original dates preserved
Attachments intact
Body intact
Thread usability
Searchability
Destination correct
Provenance retained

25. Reconciliation

Every completed migration run must be reconciled.

Required comparison:

SOURCE_COUNT
DESTINATION_COUNT
SUCCESS_COUNT
FAILURE_COUNT
SKIPPED_COUNT
DUPLICATE_COUNT
CONFLICT_COUNT

The system should prevent a migration run from being marked complete while unresolved failures remain unnoticed.

26. Message Integrity

Migration must preserve at minimum:

Subject
Sender
To
Cc
Bcc where accessible
Sent date
Received date
Body
Attachments
Internet Message-ID where accessible
Conversation/thread metadata where supported
Original recipient identity

Headers should be retained when practical.

27. Migration Audit Trail

Every migrated message should have an audit record containing:

migration_run_id
source_mailbox
source_folder
source_message_id
target_mailbox
target_folder
target_message_id
migration_timestamp
duplicate_status
classification
result
error

28. Reversibility

Migration operations should be designed so they can be rolled back where practical.

The system should know:

What moved
Where it came from
Where it went
When it moved
Which run caused it

A migration batch should be reversible independently when technically possible.

29. No Source Deletion During Initial Migration

Initial migration policy:

COPY FIRST
VALIDATE
RECONCILE
ONLY THEN CONSIDER SOURCE CLEANUP

Source mail must not be immediately deleted after copying.

30. Source Cleanup

After successful migration and a defined validation period, source cleanup may be considered.

Possible actions:

Leave source untouched
Move to source-side archive
Delete migrated folders
Delete confirmed duplicates
Retire mailbox from active mail use

All destructive cleanup requires explicit approval.

31. Empty Folder Cleanup

Empty folders should be identified separately.

Example report:

Empty folders found: 17

Safe candidates:
12

System/reserved:
3

Ambiguous:
2

Empty folders should not be deleted automatically during discovery.

32. Folder Naming Standard

Where physical folders remain, naming should be:

Short
Singular or consistently plural
Human-readable
Provider-independent
Stable over time

Avoid:

2023 Stuff
Misc2
Old Saved
Important New
Temp
Archive_old

33. Date-Based Folders

Date-based physical folder structures should generally be eliminated.

Examples:

Receipts/2024
Receipts/2025
Receipts/2026

should instead become:

classification = RECEIPT
received_year = 2026

Years are query attributes, not folder hierarchy.

34. Sender-Based Folders

Folders dedicated to individual companies or senders should generally be eliminated unless there is a strong operational reason.

Example:

Amazon
Apple
Microsoft
GitHub

should normally become metadata:

sender_domain
vendor
service
project

rather than physical folders.

35. Project-Based Folders

Project folders may be useful during active work but should not automatically become permanent mail architecture.

A project may instead be represented as:

project_id
project_name
project_status

The agent can expose an active project view dynamically.

36. Historical Search

Migration success depends on strong search.

The system should support questions such as:

Show me all mail originally stored in my old iCloud Travel folder.

Find receipts from Best Buy in 2021.

Find professional emails from DoubleLine.

Show messages originally received at jskoch67@icloud.com.

Find mail migrated from iCloud in migration batch 12.

This is why provenance metadata is mandatory.

37. Folder Mapping Review UI

The management UI should eventually expose folder mapping decisions.

Example:

SOURCE
iCloud / Purchases

Messages:
1,247

Suggested Semantic Role:
RECEIPT / PURCHASE

Suggested Disposition:
CONVERT_TO_VIEW

Suggested Destination:
Archive

Confidence:
92%

[Approve]
[Change]
[Review Messages]

38. Bulk Mapping Approval

Users should be able to approve obvious mapping groups in bulk.

Example:

Candidate Group: Receipts

Folders:
5

Messages:
3,842

[Approve All]
[Review Individually]

39. Exception Queue

Ambiguous folders or messages should enter a review queue.

Examples:

Misc
Saved
Important
Personal
Old
Archive2

The system should not guess destructively when confidence is poor.

40. Folder Rationalization Output

At the end of discovery, the system should produce:

Current folder count
Proposed physical folder count
Folders retained
Folders merged
Folders converted to views
Empty folders
Legacy-only folders
Review-required folders
Estimated message moves
Estimated duplicates
Estimated migration volume

Example:

Current physical folders: 83
Recommended physical folders: 7

Keep: 7
Merge: 21
Convert to views: 29
Historical archive: 8
Delete empty: 11
Review: 7

41. Historical Mail Versus Active Mail

The system should distinguish:

ACTIVE MAIL
HISTORICAL MAIL

Active mail participates fully in:

Historical mail primarily exists for:

Historical mail should not suddenly generate thousands of old "Action Required" items when imported.

42. Historical Import Classification

Historical messages may be semantically classified during migration, but lifecycle state should default conservatively.

Example:

Historical receipt from 2017

Classification:
RECEIPT

Attention:
ARCHIVE

Historical flag:
true

Do not infer current obligations from old mail unless explicitly requested.

43. Cutover

Once a source mailbox is no longer intended for active mail use, a formal cutover state should be recorded.

Possible states:

ACTIVE
FORWARDING
MIGRATING
READ_ONLY
LEGACY
RETIRED_FROM_MAIL

For example:

jskoch67@icloud.com

Mail State:
FORWARDING / LEGACY

Apple Services State:
ACTIVE

This distinction is required because the Apple account remains important even if its mailbox does not.

44. Proposed Target State

The likely long-term structure is:

PERSONAL
jskoch@msn.com
└── minimal physical folders
    + agent metadata
    + virtual views

PROFESSIONAL
jason@jasonkoch.io
└── minimal physical folders
    + alias awareness for jason@jasonkoch.ai

SYSTEM
platypus.software.dev@gmail.com
└── exception-oriented processing

COMMERCIAL
Jason.s.koch@gmail.com
└── aggressive low-value filtering

APPLE
jskoch67@icloud.com
└── contacts
└── shared calendars
└── mail forwarding / minimal storage

LEGACY APPLE
Jason.s.koch@icloud.com
└── inventory
└── preserve needed content
└── retire from active mail

45. Acceptance Criteria

Folder rationalization and historical migration are successfully designed when: