Inbox Agent Functional Requirements

1. Purpose

This document defines the functional behavior of the Inbox Agent application.

The application is intended to manage multiple physical mailboxes and email identities as one coordinated system while preserving the distinct purpose of each identity.

The application should reduce manual inbox review, surface important work, automate low-risk organization, and provide a consistent control plane across Microsoft, Gmail, and iCloud mail sources.

The Inbox Agent should behave as an attention-management system rather than simply as a mail client.

2. Core Product Goals

The application must:

3. Supported Mail Estate

Initial supported identities:

PERSONAL
jskoch@msn.com

PROFESSIONAL
jason@jasonkoch.io

PROJECT / AI ALIAS
jason@jasonkoch.ai
alias of jason@jasonkoch.io

COMMERCIAL
Jason.s.koch@gmail.com

SYSTEM / SERVICE
platypus.software.dev@gmail.com

APPLE INFRASTRUCTURE
jskoch67@icloud.com

LEGACY APPLE
Jason.s.koch@icloud.com

The architecture must allow additional mailboxes and aliases later.

4. Unified Inbox

The application must provide a unified inbox across all connected active mailboxes.

The unified inbox should not merely concatenate unread messages.

Instead, messages should be ordered and grouped based on:

Attention state
Priority
Identity
Message type
Age
Due date
AI confidence

The application should answer:

What actually needs my attention?

rather than:

How many unread messages exist?

5. Mailbox-Aware Workload

The system must weight mailboxes differently.

For example:

jskoch@msn.com
High relevance

jason@jasonkoch.io
High relevance

platypus.software.dev@gmail.com
Exception-driven relevance

Jason.s.koch@gmail.com
Low default relevance

A system mailbox containing hundreds of unread successful build notices must not overwhelm the user's workload view.

6. Main Navigation

Initial application navigation should include:

Home
Needs Me
Respond
Waiting
System Alerts
Read Later
Mail
Search
Rules
Identity Hygiene
Review
Migration
Settings

Historical migration features may eventually move into an administrative area after initial cleanup is complete.

7. Home Dashboard

The Home dashboard should summarize actionable email across all mailboxes.

Example:

TODAY

Needs Action             4
Responses Owed           3
Waiting                  6
System Alerts            1
Read Later               5

Processed Automatically  73

The dashboard should emphasize work remaining rather than raw mail volume.

8. Needs Me View

The Needs Me view should aggregate:

ACTION
RESPOND
SYSTEM_ALERT
High-priority unresolved messages
Low-confidence messages requiring review

Users should be able to filter by:

Mailbox
Identity
Priority
Classification
Sender
Age
Due date
Project

9. Respond View

Respond should show messages where the user likely owes a reply.

Each item should display:

Sender
Subject
Mailbox / identity
Age
Priority
Reason response is believed necessary
Suggested response summary

Optional actions:

Open thread
Draft response
Mark resolved
Convert to action
Dismiss

10. Waiting View

Waiting should show conversations where the user has requested action or information from another party.

Each item should show:

Recipient
Subject
What Jason is waiting for
Date of last outbound message
Elapsed waiting time
Expected response date if known
Priority

The system should automatically remove an item from Waiting when a relevant response arrives and re-evaluate the conversation.

11. Stale Waiting Detection

The agent should identify conversations that have remained in Waiting beyond a reasonable period.

Possible signals:

Explicit promised response date passed
Explicit deadline passed
No reply after user-defined number of days
Pattern suggests follow-up is appropriate

The system may recommend:

Follow up.

It may generate a draft.

It must not initially send that follow-up autonomously.

12. System Alerts View

System Alerts should surface only meaningful exceptions from system/service mail.

Examples:

Deployment failed
Build failed
Security vulnerability
Billing failure
Repository invitation
Certificate expiration
Authentication failure
Production incident

Success notifications should generally remain out of this view.

13. Read Later View

The user should have a cross-mailbox Read Later queue.

Typical content:

Technical newsletters
Long-form articles
Industry information
Useful announcements
Research material

Read Later should support:

Mark read
Archive
Keep
Dismiss
Promote to Action

14. Message Detail

Opening a message in Inbox Agent should display normal mail content plus agent-derived context.

Example:

From:
Jane Smith

To:
jason@jasonkoch.io

Received:
...

Classification:
PROFESSIONAL

Attention:
RESPOND

Priority:
HIGH

Agent Summary:
Jane is requesting confirmation that the revised proposal is approved.

Suggested Next Action:
Reply with approval status.

Confidence:
High

The user should be able to correct any agent-derived value.

15. Message Summary

The agent should be able to generate concise summaries of individual messages.

For threads, it should summarize:

Current issue
Key decisions
Outstanding questions
Who owes the next action
Relevant dates

The summary should not replace access to the original message.

16. Thread Awareness

The agent should reason at the conversation/thread level where possible.

It should understand:

Who initiated the conversation
What questions were asked
Which questions were answered
What remains unresolved
Who currently owes the next action

Attention state should usually apply to the conversation rather than blindly to each message.

17. Natural-Language Mail Commands

The application should support natural-language commands.

Examples:

Show me everything I need to respond to.

What am I waiting on?

Find my receipt for the monitor I bought last year.

Show emails from my accountant.

Find all travel confirmations for Boston.

What system alerts did I get this week?

Show me emails that probably went to the wrong address.

Archive all successful Vercel deployment emails.

Why is this message marked Action?

Show all mail originally migrated from iCloud.

The system should translate these requests into searches, views, or proposed actions.

18. Search

Search must span connected mailboxes where provider capabilities allow.

Search criteria should include:

Sender
Recipient
Original recipient
Subject
Body
Date
Attachment name
Mailbox
Provider
Classification
Attention state
Priority
Project
Vendor
Migration provenance
Original folder

Search should support both structured and natural-language queries.

19. Cross-Mailbox Search Results

Search results must clearly show where each message lives.

Example:

Microsoft
jskoch@msn.com

Gmail
platypus.software.dev@gmail.com

Historical source
jskoch67@icloud.com

The user should never need to guess which mailbox contains a result.

20. Identity Awareness

Every incoming message should be associated with:

Physical mailbox
Delivered-to identity
Original recipient
Provider

This is particularly important for aliases such as:

jason@jasonkoch.ai

which shares the physical mailbox of:

jason@jasonkoch.io

21. Identity Hygiene

The application should identify mail being sent to the wrong identity.

Example:

Sender:
Retailer

Received at:
jskoch@msn.com

Classification:
MARKETING

Preferred identity:
Jason.s.koch@gmail.com

The system should recommend:

Update this account to use the commercial email address.

It should not automatically change external accounts.

22. Identity Hygiene Dashboard

Identity Hygiene should summarize recurring misrouted correspondence.

Example:

Potential identity changes

Amazon
18 messages/month
Current: jskoch@msn.com
Recommended: Jason.s.koch@gmail.com

Development service
12 messages/month
Current: jason@jasonkoch.io
Recommended: platypus.software.dev@gmail.com

The user should be able to:

Accept recommendation
Ignore
Mark current identity correct
Create classification rule

23. Deterministic Rules

The application must support user-approved deterministic rules.

Rule conditions may include:

Mailbox
Recipient identity
Sender
Sender domain
Subject
Message headers
Known service
Classification
Attachment presence
Mailing-list indicators

Rule actions may include:

Classify
Set priority
Set attention state
Archive
Mark read
Apply category
Move
Suppress from workload
Flag
Create review item

24. Rule Precedence

Rules should execute according to explicit precedence.

Suggested ordering:

1. Security constraints
2. Explicit user overrides
3. Mailbox-specific rules
4. Identity-specific rules
5. Sender/domain rules
6. Approved learned rules
7. AI classification

The UI should make conflicts visible.

25. Rule Management

The Rules screen should show:

Rule name
Status
Scope
Conditions
Actions
Priority/order
Created by
Created date
Last triggered
Trigger count

Users should be able to:

Enable
Disable
Edit
Duplicate
Delete
Test
View affected messages

26. Rule Simulation

Before activating a new rule, the user should be able to run it against historical mail.

Example:

Proposed rule:

Sender domain = github.com
Subject contains "workflow run succeeded"

Action:
Archive
Priority:
BACKGROUND

Would have matched:
1,847 messages

False-positive review sample:
20 messages

This should help prevent destructive or overly broad rules.

27. Rule Suggestions

The agent should identify repeated behavior and recommend automation.

Example:

You archived 27 messages from this sender without responding.

Suggested rule:
Archive future messages from this sender.

Confidence:
High

The rule does not become active without approval.

28. User Corrections

When the user changes:

Classification
Attention state
Priority
Retention
Identity recommendation

the system should record the correction.

The application should distinguish:

Single correction
Repeated pattern
Approved permanent rule

29. Draft Replies

The agent should generate draft replies on request or when a message is classified RESPOND.

Drafts should consider:

Thread history
User's prior messages in the thread
Requested action
Tone
Known context

Initial behavior:

GENERATE DRAFT
DO NOT SEND

The user may edit and send from the selected mail client or later from the Inbox Agent if sending capability is enabled.

30. Suggested Actions

Messages may expose context-sensitive suggested actions.

Examples:

Draft Reply
Mark Complete
Move to Waiting
Archive
Read Later
Create Rule
Change Priority
Correct Classification
Mark as Wrong Identity
Find Related Mail

31. Approval Queue

Actions requiring approval should be grouped into a Review or Approval queue.

Potential items:

New rule suggestions
Bulk archive operations
Potential duplicate cleanup
Folder migration mappings
Unsubscribe suggestions
External identity-change recommendations
Deletion candidates
Low-confidence classifications

32. Batch Operations

Users should be able to perform batch operations across mailboxes.

Examples:

Archive
Mark read
Classify
Set priority
Assign project
Dismiss
Approve rule

Batch actions must show the number of affected messages before execution.

Destructive actions require explicit confirmation.

33. Undo

Low-risk automated actions should be reversible.

The UI should support:

Undo last action
Undo batch
Restore original folder
Restore previous classification
Restore previous attention state

Undo should use the audit history rather than relying solely on UI state.

34. Audit History

The application must provide an audit view.

Each event should show:

Timestamp
Message/thread
Mailbox
Action
Previous state
New state
Rule or AI responsible
Confidence
Reason
Undo availability

The user should be able to filter by:

Mailbox
Rule
Action type
Date
Automated/manual

35. Explainability

The user should be able to ask:

Why did you do this?

Examples:

Why was this archived?

Why is this marked High?

Why is this in Waiting?

Why are you recommending Gmail for this sender?

The answer should reference:

Rules matched
Message characteristics
Conversation state
Historical user behavior
AI confidence

without exposing hidden model reasoning.

36. Daily Brief

The application should be able to produce a daily summary.

Suggested structure:

Needs Action
Responses Owed
Waiting / Follow-Up
System Alerts
Important New Mail
Read Later
Automatically Processed
Identity Hygiene Suggestions

The brief should prioritize significance over message count.

37. On-Demand Briefs

Users should also be able to request:

What's important right now?

What changed since this morning?

What came in overnight?

What do I still owe people?

What am I waiting for?

What's happening in my system mailbox?

38. Commercial Mail Behavior

The commercial Gmail mailbox should support aggressive noise reduction.

The agent should be comfortable automatically processing approved classes such as:

Promotions
Retail announcements
Coupons
Marketing
Routine newsletters

The commercial mailbox should contribute minimally to the main workload dashboard unless a message is classified as important.

39. System Mail Behavior

The system/service mailbox should operate using exception-oriented logic.

Expected model:

Normal automated event
→ suppress / archive

Failure
→ alert

Security event
→ alert

Action required
→ Needs Me

Invitation
→ Needs Me

The system mailbox should be summarized rather than manually reviewed.

40. Historical Mail Behavior

Historical imported mail should remain searchable but should not create current workload items by default.

Historical content should support:

Search
Reference
Summarization
Classification
Provenance queries

It should not automatically produce:

Action
Respond
Waiting
System Alert

unless the user explicitly asks the system to analyze old mail for unresolved obligations.

41. Attachment Awareness

The agent should understand attachment presence and basic attachment metadata.

Examples:

PDF invoice
Receipt
Contract
Image
Spreadsheet
Calendar attachment

Search should support attachment filename and type where provider APIs permit.

Attachment content analysis may be added separately.

42. Project Classification

Messages may optionally be associated with projects.

Examples:

PocketSomm
Inbox Agent
Executive Portfolio
Website
Other development projects

Project assignment should not require a physical mail folder.

The system should support automatic project inference with user correction.

43. Sender Profiles

The application may maintain lightweight sender profiles.

Possible attributes:

Known person/company
Typical classification
Default priority
Preferred identity
Human vs automated
Historical interaction level
Approved rules

This should improve classification consistency.

44. Contacts Integration

Contacts remain authoritative in iCloud initially.

The Inbox Agent should be able to use known contacts as a signal for:

Human correspondence
Importance
Relationship recognition
Preferred identity

The application should not require moving contacts to Microsoft.

45. Calendar Awareness

Shared family calendars remain in iCloud.

Future calendar integration may help interpret mail such as:

Meeting invitations
Travel
Appointments
Reservations
Events

Calendar integration is useful but should not be required for the first mail-management release.

46. Notification Policy

The application should avoid replacing inbox clutter with notification clutter.

Notifications should be limited primarily to:

CRITICAL
Selected HIGH priority
Explicit user-defined alerts

Everything else should be surfaced in the dashboard or summaries.

47. Mail Client Independence

The system must not require Outlook as the primary user interface for mail.

Users may continue to use:

Outlook
Outlook Web
Other compatible clients
Inbox Agent UI

Apple Mail is excluded as a desired client.

The Inbox Agent remains the automation and intelligence layer regardless of client choice.

48. Settings

Settings should include:

Connected mailboxes
Identity definitions
Mailbox weighting
Attention thresholds
Priority behavior
AI confidence thresholds
Rule management
Notification preferences
Retention preferences
Daily brief preferences
Migration configuration
Audit retention

49. Provider Health

The application should display connector health.

Example:

Microsoft Personal
Connected

Microsoft Professional
Connected

Gmail Commercial
Connected

Gmail System
Connected

iCloud
Connected / Read-only

Failures should be visible and actionable.

50. Graceful Degradation

If one provider is unavailable:

51. Initial Automation Boundary

The first production version may autonomously perform only approved low-risk actions.

Examples:

Classify
Tag
Set metadata
Archive explicitly approved low-value categories
Mark approved automated mail read
Apply approved rules
Generate summaries
Generate drafts

Actions requiring approval:

Send email
Permanent delete
Mass delete
Create forwarding rules
Change mailbox settings
Modify account security
Change external account email
Unsubscribe from external services

52. Functional Acceptance Criteria

The Inbox Agent satisfies the initial functional requirements when it can: