Mail Estate Migration + Organization Specification

1. Purpose

The goal is to simplify and centralize email management across multiple email addresses while preserving the user's preferred identities and existing family calendar setup.

The project will reduce folder sprawl, eliminate redundant organizational structures, consolidate historical mail where practical, and establish a clean foundation for a future AI-powered Inbox Agent.

The desired end state is:

• Microsoft is the primary email platform and canonical mail store.
• iCloud continues to host shared family calendars.
• Existing email addresses can remain active as identities.
• Email organization is standardized across accounts.
• The number of physical folders is significantly reduced.
• AI classification and virtual views handle much of the organization that folders previously attempted to provide.
• Historical mail remains searchable and traceable to its original account and provider.
• The system remains independent of any specific desktop email client.

2. Guiding Principles

2.1 Separate Identity from Storage

An email address does not need to determine where mail is permanently stored.

The system should distinguish between:

• Email identity
• Mail provider
• Physical mailbox
• Historical mail storage
• Calendar provider

For example, multiple personal or custom-domain addresses may ultimately deliver into Microsoft-hosted mailboxes while preserving the original recipient address.

2.2 Microsoft as the Canonical Mail Platform

Microsoft should become the preferred platform for active email and long-term mail storage unless a technical or operational reason requires otherwise.

The target architecture is:

Email Identities
      |
      v
Microsoft-hosted mail
      |
      v
Canonical Mail Store

Existing iCloud-hosted mail may be migrated into Microsoft.

iCloud will continue to be used for shared family calendars.

2.3 Calendar Hosting Is Independent

Family calendar sharing will remain on iCloud.

There is no requirement to move calendars to Microsoft simply because mail is consolidated there.

Target:

MAIL
Microsoft

CALENDARS
iCloud Shared Calendars

2.4 Minimize Physical Folders

Folders should represent stable, broad organizational concepts.

Folders should not attempt to encode every possible characteristic of an email.

Avoid structures such as:

Finance
  Purchases
    Online
      Amazon
        2026

Prefer:

Finance
  Receipts

with metadata representing:

Vendor: Amazon
Year: 2026
Type: Purchase

3. Target Organizational Model

The initial proposed physical folder structure is intentionally small.

Inbox

Action
Waiting

Personal
  Family
  Travel

Finance
  Receipts
  Taxes

Development
  GitHub
  Infrastructure

Reference

Newsletters

Archive

This structure is preliminary and should be refined after reviewing the existing mail estate.

The target should generally remain below approximately 10–15 primary organizational concepts.

4. Physical Folders vs. Virtual Views

Physical folders will be used only where moving a message provides meaningful organizational value.

Many concepts should instead become virtual views.

Examples:

Needs My Attention
Waiting on Someone
Important Unread
Receipts This Month
Upcoming Travel
Development Alerts
Family
Bills
Newsletters to Read

These are queries over metadata rather than physical folders.

Example:

Needs My Attention

requires_action = true
AND completed = false
AND deleted = false

This prevents folder proliferation and allows a message to appear in multiple useful contexts without duplication.

5. Message Metadata Model

The Inbox Agent should maintain metadata describing each message.

Initial metadata should include:

The exact implementation may use Microsoft categories, a local database, or a combination of both.

6. Folder Inventory Phase

Before moving mail, the system will inventory existing folders across all mailboxes.

For every folder, capture:

Account
Provider
Folder name
Full folder path
Message count
Unread count
Oldest message
Newest message
Approximate storage size
Subfolders

The inventory will then identify:

• Duplicate folder names
• Semantically equivalent folders
• Empty folders
• Low-value folders
• Legacy folders
• Folders containing mostly automated mail
• Folders that should be converted into virtual views
• Folders requiring manual review

Example:

No folders will initially be deleted automatically.

7. Folder Mapping

Every existing folder should receive a migration disposition.

Valid dispositions:

KEEP
MERGE
RENAME
ARCHIVE
CONVERT_TO_VIEW
REVIEW
DELETE_EMPTY

Example:

iCloud / Purchases
    -> MERGE
    -> Finance / Receipts

Microsoft / GitHub
    -> KEEP
    -> Development / GitHub

iCloud / Important
    -> CONVERT_TO_VIEW
    -> Important

Microsoft / Misc
    -> REVIEW

8. Historical iCloud Mail Migration

Historical iCloud mail should be evaluated for migration into Microsoft.

The migration should preserve provenance.

Every migrated message should retain enough information to answer:

Where was this message originally stored?

Which address received it?

Which provider did it come from?

Which folder was it in?

At minimum, preserve:

source_provider
source_mailbox
original_recipient
original_folder
migration_date

The project should not simply merge mail without retaining this context.

9. Migration Safety

Migration should use a staged process.

Stage 1 — Inventory

Read-only discovery.

No changes.

Stage 2 — Mapping

Generate proposed mappings.

No changes.

Stage 3 — Dry Run

Calculate what would move and where.

Produce counts and exceptions.

Stage 4 — Pilot

Move a small controlled sample.

Validate:

• Message integrity
• Dates
• Attachments
• Sender/recipient information
• Thread behavior
• Searchability
• Folder placement

Stage 5 — Bulk Migration

Perform approved migration.

Stage 6 — Reconciliation

Compare:

Source message count
Destination message count
Failed messages
Skipped messages
Duplicate messages
Attachment failures

Stage 7 — Cleanup

Only after successful reconciliation should old folders be considered for deletion.

10. Duplicate Handling

The migration process must detect potential duplicate messages.

Possible matching keys may include:

Internet Message ID
Sender
Recipient
Timestamp
Subject
Body hash
Attachment hash

Internet Message ID should be preferred when available.

Duplicates should not automatically be permanently deleted during initial migration.

Instead:

duplicate_status = suspected
duplicate_status = confirmed
duplicate_status = unique

11. Initial Inbox Agent Classification Model

Messages should initially be classified into a limited set of semantic categories.

Proposed categories:

Action Required
Waiting
Information
Finance / Receipt
Development / Systems
Newsletter / Reading
Personal / Family
Travel
Noise
Unknown

The list may evolve, but categories should remain broader than folders.

12. Rule Engine

Deterministic rules should execute before AI classification.

Processing order:

New Message
    |
    v
Known Rule?
    |
  YES ----> Execute deterministic rule
    |
   NO
    |
    v
AI Classification
    |
    v
Confidence Evaluation
    |
    +---- High confidence ---> Suggested/Automatic action
    |
    +---- Low confidence ----> Review queue

Example deterministic rule:

IF sender_domain = "github.com"
AND message_type = "notification"
THEN
    category = "Development / Systems"

AI should handle ambiguous semantic decisions rather than replacing reliable rules.

13. Rule Scope

Rules should support different scopes.

GLOBAL

PROVIDER

MAILBOX

EMAIL ADDRESS

SENDER

DOMAIN

PROJECT

Example:

GLOBAL

GitHub Dependabot notices
    -> Development / GitHub

Example:

MAILBOX

Messages sent to a specific business address
    -> classify according to that mailbox's business context

14. Rule Learning

The future agent should identify repetitive manual actions and suggest new rules.

Example:

You moved 18 messages from GitHub to
Development / GitHub during the past month.

Suggested Rule:

Messages from notifications@github.com
-> Development / GitHub

[Approve]
[Modify]
[Ignore]

Rules should never silently become permanent merely because the AI noticed a pattern.

15. Agent Permissions

Initial agent capabilities:

ALLOWED

Read messages
Search messages
Classify messages
Apply metadata
Apply categories
Move messages
Archive messages
Mark read/unread
Flag messages
Create draft responses
Suggest rules
Generate summaries

Initially protected actions:

REQUIRE USER APPROVAL

Send email
Delete email permanently
Create forwarding rules
Modify mailbox security settings
Change account configuration
Mass-delete messages

The permission model can become more autonomous later.

16. Email Client Independence

The architecture must not depend upon Outlook being the primary email client.

Possible future clients include:

Outlook
Outlook Web
Spark
Canary
Thunderbird
Other IMAP-compatible clients
Custom Inbox Agent UI

The client is considered a presentation layer.

The canonical data and automation live behind it.

Apple Mail is explicitly excluded from consideration.

17. Proposed Application Architecture

Initial implementation concept:

                  Inbox Agent
                    Next.js
                       |
         +-------------+-------------+
         |                           |
    Agent Engine                 Management UI
         |
    Rule Engine
         |
    AI Classifier
         |
    Mail Connectors
         |
   +-----+----------------+
   |                      |
Microsoft Graph        iCloud / IMAP

A database should maintain:

Mail accounts
Mail identities
Folder inventory
Folder mappings
Rules
Message classifications
Agent decisions
Migration runs
Audit logs
User approvals

18. Auditability

Every automated action should be auditable.

Example:

2026-09-05 10:42

Message:
"Your GitHub deployment completed"

Action:
Moved to Development / GitHub

Reason:
Rule R-0041

Rule:
sender_domain = github.com

Original Folder:
Inbox

Destination:
Development / GitHub

AI decisions should additionally record:

Model
Classification
Confidence
Reason summary
Rule override, if applicable

19. Reversibility

Automated operations should be reversible wherever possible.

The system should maintain an action history sufficient to support:

Undo last action

Undo all actions from a processing run

Restore original folder

Restore original category

Permanent deletion should not be part of the early agent lifecycle.

20. Initial Project Phases

Phase 0 — Mail Estate Definition

Document:

• Every email address
• Provider
• Current role
• Whether actively used
• Whether it receives mail
• Whether mail is stored there
• Whether it should remain independent
• Approximate historical mail volume

Phase 1 — Discovery

Connect read-only to mail providers.

Generate:

• Account inventory
• Folder inventory
• Message counts
• Storage estimates
• Folder similarity analysis

Phase 2 — Organization Design

Define:

• Canonical folder structure
• Folder mappings
• Virtual views
• Classification taxonomy
• Retention policy

Phase 3 — Migration

Migrate approved historical mail into Microsoft.

Preserve provenance.

Validate completeness.

Phase 4 — Rule Engine

Implement deterministic mailbox rules.

Initially run in suggestion mode.

Phase 5 — AI Classification

Implement semantic classification for messages not handled by deterministic rules.

Include confidence thresholds.

Phase 6 — Inbox Agent

Add:

• Daily inbox summary
• Needs-attention view
• Waiting view
• Suggested rules
• Draft responses
• Natural-language mailbox queries

Phase 7 — Controlled Autonomy

Allow selected trusted actions to execute automatically.

Examples:

Archive known newsletters
File receipts
Organize GitHub notifications
Mark low-value automated notices as read

Sending email and permanent deletion remain separately controlled.

21. Initial Success Criteria

The first major milestone will be considered successful when:

• All active mail accounts are inventoried.
• Every current folder has a proposed disposition.
• Duplicate organizational concepts have been identified.
• A canonical folder hierarchy has been approved.
• Historical iCloud mail has an approved migration strategy.
• Mail provenance can be retained after migration.
• No migration requires dependency on a particular email client.
• Microsoft is capable of functioning as the canonical mail store.
• iCloud family calendars remain unaffected.
• The agent can eventually organize all supported mailboxes using one consistent taxonomy.

22. Decisions Already Made

The following decisions are currently considered established:

Microsoft:
Preferred canonical email platform.

iCloud:
Continue hosting shared family calendars.

Historical iCloud email:
Candidate for migration into Microsoft.

Outlook:
Permitted but not required as the email client.

Apple Mail:
Excluded.

Folder strategy:
Reduce physical folders substantially.

Organization strategy:
Use physical folders + semantic metadata + virtual views.

Automation strategy:
Rules first, AI second.

Initial AI authority:
Organize and draft, but do not autonomously send or permanently delete.

23. Next Discovery Dataset

Before implementation begins, create an account inventory containing one row per email identity.

Required fields:

This inventory becomes the authoritative starting point for the migration plan.