Inbox Agent Message Lifecycle and Policy Specification

1. Purpose

This document defines how the Inbox Agent should evaluate, classify, prioritize, retain, and surface email across the user's mail estate.

The core principle is:

Email should be organized around attention and action, not around folder location.

Physical folders should remain minimal. Most organization should be expressed through metadata, classifications, agent state, and virtual views.

2. Message Lifecycle

Every incoming message should move through a consistent lifecycle.

NEW MESSAGE
    |
    v
INGEST
    |
    v
IDENTIFY MAILBOX / IDENTITY
    |
    v
APPLY DETERMINISTIC RULES
    |
    v
AI CLASSIFICATION IF NEEDED
    |
    v
DETERMINE ATTENTION STATE
    |
    v
DETERMINE PRIORITY
    |
    v
DETERMINE RETENTION
    |
    v
APPLY ACTION
    |
    v
SURFACE OR ARCHIVE

The agent must distinguish between:

These are separate dimensions.

3. Inbox Philosophy

The Inbox represents messages that are not yet sufficiently processed.

Inbox should not become permanent storage.

A message should remain in the Inbox when:

A message should leave the Inbox when:

Reading a message alone should not automatically mean it is resolved.

4. Attention States

Each message or conversation may have one primary attention state.

Initial states:

UNPROCESSED
ACTION
RESPOND
WAITING
READ_LATER
REFERENCE
SYSTEM_ALERT
ARCHIVE
DISCARD_CANDIDATE

4.1 UNPROCESSED

The message has not yet been confidently classified.

Typical reasons:

4.2 ACTION

The user needs to perform a non-email action.

Examples:

Action items should support:

Due date
Priority
Action summary
Related person
Related project
Completion state

4.3 RESPOND

The user owes someone an email response.

The agent should differentiate this from ACTION.

Example:

Message:
"Can you send me the revised proposal?"

Attention:
RESPOND

Suggested action:
Draft reply

4.4 WAITING

The user has already taken action or sent a response and is waiting for another party.

The agent should create WAITING states automatically where confidence is high.

Example:

Jason:
"I've attached the signed form. Please let me know when the account has been updated."

State:
WAITING

Waiting on:
Recipient

Expected response:
Confirmation of account update

When the recipient replies, the conversation should automatically leave WAITING and be re-evaluated.

4.5 READ_LATER

The message is worth consuming but does not require immediate action.

Examples:

READ_LATER should be a virtual queue, not necessarily a physical folder.

4.6 REFERENCE

The message contains useful information that should be retained but does not need to be surfaced regularly.

Examples:

4.7 SYSTEM_ALERT

The message is automated but requires attention.

Examples:

Routine successful system events should not become SYSTEM_ALERT.

4.8 ARCHIVE

The message should be retained but does not require user attention.

Examples:

4.9 DISCARD_CANDIDATE

The message appears to have little or no long-term value.

Examples:

Initially, DISCARD_CANDIDATE means:

Classify
Hide from primary views
Retain temporarily
Do not permanently delete automatically

Permanent deletion remains governed by a separate approval and retention policy.

5. Message Classification

Attention state answers:

What should Jason do about this?

Classification answers:

What kind of message is this?

These should remain independent.

Initial semantic classifications:

PERSONAL
FAMILY
PROFESSIONAL
PROJECT
DEVELOPMENT
SYSTEM
SECURITY
FINANCIAL
RECEIPT
PURCHASE
TRAVEL
ADMINISTRATIVE
NEWSLETTER
MARKETING
SOCIAL
LEGAL
OTHER
UNKNOWN

A message may have one primary classification and multiple secondary tags.

Example:

Primary Classification:
FINANCIAL

Secondary:
RECEIPT
PURCHASE

Attention:
ARCHIVE

6. Priority Model

Priority should represent how quickly the user needs to become aware of the message.

Proposed values:

CRITICAL
HIGH
NORMAL
LOW
BACKGROUND

6.1 CRITICAL

Immediate attention may be required.

Examples:

CRITICAL should be rare.

6.2 HIGH

Important and likely needs attention soon.

Examples:

6.3 NORMAL

Standard correspondence worth reviewing.

Examples:

6.4 LOW

Useful but not time-sensitive.

Examples:

6.5 BACKGROUND

Should ordinarily not interrupt or clutter.

Examples:

7. Attention Is Not the Same as Priority

These dimensions must remain separate.

Example:

Message:
Annual tax document available

Classification:
FINANCIAL

Attention:
ACTION

Priority:
NORMAL

Another example:

Message:
Production authentication failure

Classification:
SYSTEM / SECURITY

Attention:
SYSTEM_ALERT

Priority:
CRITICAL

8. Human Correspondence Policy

Messages written by actual people should receive higher default attention than automated mail.

Signals indicating human correspondence may include:

Human messages should not be automatically archived unless a strong rule exists.

9. Response Detection

The agent should identify messages that likely require a response.

Signals may include:

Direct question
Request for information
Request for confirmation
Request for approval
Scheduling request
Explicit "please respond"
Conversation awaiting acknowledgement

The agent should create:

attention_state = RESPOND

and optionally generate a draft reply.

Draft generation does not imply authorization to send.

10. Waiting Detection

The agent should inspect sent mail and conversation history.

A conversation should become WAITING when the user:

Example:

Sent:
"Can you confirm whether the refund was issued?"

Result:
WAITING

Waiting on:
Recipient

Subject:
Refund confirmation

11. Waiting Follow-Up

The agent should be capable of identifying stale WAITING conversations.

Future behavior may include:

Waiting 3 days
Waiting 7 days
Waiting past expected date
Waiting past explicit deadline

The system may suggest:

You asked for a response seven days ago and have not received one.

The agent may draft a follow-up but should not autonomously send it during initial phases.

12. Completion Detection

An ACTION or RESPOND item should remain active until:

Reading the message does not equal completion.

13. Receipt and Purchase Policy

Routine receipts and purchase confirmations should generally not remain in Inbox.

Default workflow:

Receipt received
    |
    v
Classify
    |
    v
Extract metadata
    |
    v
Check for unusual condition
    |
    +---- Normal ----> Archive
    |
    +---- Problem ---> Action / Alert

Useful metadata may include:

Merchant
Transaction date
Amount
Order number
Product/service
Payment method indicator
Return deadline
Subscription indicator

Examples requiring attention:

14. Travel Policy

Travel-related correspondence should be retained and made discoverable without forcing everything into folders.

Potential metadata:

Trip
Destination
Confirmation number
Travel date
Return date
Carrier
Hotel
Rental car
Traveler

Routine travel confirmations:

Classification:
TRAVEL

Attention:
REFERENCE

Priority:
NORMAL

Travel disruptions should become:

Classification:
TRAVEL

Attention:
ACTION

Priority:
HIGH

15. Financial Policy

Financial correspondence should be handled conservatively.

Potential categories:

Statement
Bill
Receipt
Tax
Bank alert
Insurance
Investment
Payment confirmation
Payment failure
Fraud/security

Examples:

Routine statement:

Classification:
FINANCIAL

Attention:
REFERENCE

Priority:
LOW

Payment failure:

Classification:
FINANCIAL

Attention:
ACTION

Priority:
HIGH

Fraud alert:

Classification:
FINANCIAL / SECURITY

Attention:
ACTION

Priority:
CRITICAL

16. System / Service Mail Policy

The system/service mailbox:

platypus.software.dev@gmail.com

should be treated differently from human-facing mailboxes.

The normal goal is:

Process large volumes of automated mail while surfacing only exceptions.

Examples:

Build succeeded
→ BACKGROUND / ARCHIVE

Deployment succeeded
→ BACKGROUND / ARCHIVE

Build failed
→ SYSTEM_ALERT / HIGH

Deployment failed
→ SYSTEM_ALERT / HIGH

Security alert
→ SYSTEM_ALERT / CRITICAL or HIGH

Dependency vulnerability
→ SYSTEM_ALERT

Repository invitation
→ ACTION

Billing failure
→ ACTION / HIGH

The unread count of the system mailbox should not be treated as a meaningful measure of user workload.

17. Marketing and Commercial Policy

The preferred destination for commercial and low-value correspondence is:

Jason.s.koch@gmail.com

Examples:

Messages of this type received at higher-value identities should generate an Identity Hygiene recommendation when appropriate.

Example:

Received at:
jskoch@msn.com

Sender:
Retailer

Classification:
MARKETING

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

Recommendation:
Update account email

18. Identity Hygiene

The agent should identify correspondence arriving at an inappropriate identity.

Identity policy:

PERSONAL
jskoch@msn.com

PROFESSIONAL
jason@jasonkoch.io

PROJECTS / AI
jason@jasonkoch.ai
(alias of jason@jasonkoch.io mailbox)

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

COMMERCIAL / LOW VALUE
Jason.s.koch@gmail.com

APPLE INFRASTRUCTURE
jskoch67@icloud.com

Identity Hygiene should generate recommendations, not automatically change external accounts.

19. Newsletter Policy

Newsletters should not normally clutter the Inbox.

The agent should distinguish between:

VALUABLE NEWSLETTER
→ READ_LATER

LOW-VALUE NEWSLETTER
→ ARCHIVE

PROMOTIONAL NEWSLETTER
→ DISCARD_CANDIDATE

Repeated user behavior should influence future classification.

Example:

If the user repeatedly archives a newsletter without opening it, the agent may recommend:

Automatically archive this newsletter.

If the user repeatedly ignores it, the agent may recommend:

Unsubscribe or redirect this subscription to the commercial mailbox.

20. Retention Model

Retention is independent of attention.

Proposed retention states:

PERMANENT
LONG_TERM
STANDARD
TEMPORARY
DISCARD_CANDIDATE

PERMANENT

Examples:

LONG_TERM

Examples:

STANDARD

Default archived correspondence.

TEMPORARY

Examples:

DISCARD_CANDIDATE

Low-value content eligible for future cleanup.

21. Deletion Policy

Initial system behavior:

NO autonomous permanent deletion.

The agent may:

Permanent bulk deletion requires explicit approval.

22. Spam Policy

Provider-native spam and junk filtering should remain the first line of defense.

The Inbox Agent should not attempt to replace Microsoft or Gmail spam filtering.

The agent may supplement provider filtering by identifying:

23. Deterministic Rules Before AI

Processing precedence:

1. Security constraints
2. Explicit user rules
3. Known sender/domain rules
4. Known system event rules
5. Existing learned approved rules
6. AI classification
7. User review when confidence is insufficient

The AI must not override an explicit user rule unless the system detects a safety issue or the rule is invalid.

24. AI Confidence

AI-derived classifications should retain confidence.

Suggested model:

HIGH
MEDIUM
LOW

Example behavior:

High confidence

Allow approved low-risk automatic behavior.

Medium confidence

Classify but avoid destructive or highly visible actions.

Low confidence

Leave visible and place in review queue.

25. Virtual Views

The application should expose logical views that span multiple mailboxes.

Initial views:

Needs Me
Respond
Waiting
System Alerts
Read Later
Financial
Travel
Professional
Projects
Family
Receipts
Recently Archived
Review Queue

These views should not require corresponding physical folders.

26. Cross-Mailbox Views

Views should aggregate messages from multiple physical mailboxes.

Example:

NEEDS ME

jskoch@msn.com
    3

jason@jasonkoch.io
    2

platypus.software.dev@gmail.com
    1 system alert

Total:
6

The user should not need to manually visit each mailbox to understand their workload.

27. Daily Summary

A future Daily Summary should summarize attention, not unread counts.

Example:

Morning Inbox Brief

Needs action: 4
Responses owed: 3
Waiting: 6
System alerts: 1
Read later: 5

Automatically processed overnight: 73

Commercial messages redirected/archived: 21
System success notifications archived: 38
Receipts archived: 9
Other informational mail archived: 5

The goal is:

Tell the user what matters, not how much mail exists.

28. User Corrections

Every user correction should become learning data.

Example:

Agent:
READ_LATER

User:
No, this sender is always important.

Result:
Record correction.

Potential suggestion:
Create sender rule.

The system should distinguish between:

One-time correction
Pattern
Approved rule

A single correction should not necessarily become a permanent rule.

29. Rule Suggestions

The agent may propose rules when repeated behavior is detected.

Example:

Observed:

23 messages from sender X
22 manually archived
0 responded to
1 opened

Suggested rule:

Automatically archive messages from sender X.

[Approve]
[Modify]
[Reject]

Approved rules become deterministic and execute before AI.

30. Safety and Approval Boundaries

Initially permitted without per-message approval:

Read
Classify
Tag
Categorize
Mark read/unread
Archive known low-risk messages
Move according to explicit approved rules
Create virtual state
Generate summaries
Generate draft replies
Recommend rules

Require approval:

Send email
Permanent deletion
Mass deletion
Create forwarding rules
Modify mailbox configuration
Modify account security
Change external service email address
Unsubscribe where action could affect an external account

These boundaries may be relaxed later on a rule-by-rule basis.

31. Audit Requirements

Every automated operation should record:

Timestamp
Mailbox
Message identifier
Previous state
New state
Action
Rule or model responsible
Classification
Confidence
Reason summary
Reversibility information

The system must be able to answer:

Why did the agent do this?

32. Design Principle

The central design principle is:

MAILBOX ≠ WORKLOAD

UNREAD ≠ IMPORTANT

FOLDER ≠ MEANING

READ ≠ COMPLETE

The Inbox Agent exists to transform a collection of mailboxes into a unified representation of:

What needs attention
What needs action
What needs a response
What the user is waiting on
What should be retained
What can safely disappear into the background