Inbox Agent UI and User Experience Requirements

1. Purpose

This document defines the user experience, primary screens, interaction patterns, information hierarchy, and usability requirements for the Inbox Agent.

The goal is not to reproduce a traditional email client.

The goal is to provide a clear operational interface for:

The experience should remain compatible with either:

The UI must not assume Outlook is the permanent presentation layer.

2. UX Principles

The application should follow these principles:

ATTENTION OVER INBOX COUNT

ACTION OVER FOLDER NAVIGATION

CONVERSATIONS OVER INDIVIDUAL MESSAGES

EXCEPTIONS OVER NOISE

EXPLANATION OVER MYSTERY

REVERSIBILITY OVER FEAR

CONSISTENCY OVER PROVIDER-SPECIFIC BEHAVIOR

3. Primary User Goal

The default experience should answer:

What do I need to deal with?

The application should not force the user to begin by choosing a mailbox.

Mailbox location is secondary metadata.

4. Primary Navigation

Recommended primary navigation:

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

Administrative or low-frequency items may be grouped separately:

Migration
Provider Health
Audit
Developer / Diagnostics

5. Home Dashboard

The Home screen should provide a concise operational summary.

Example:

Good morning

Needs Action        4
Responses Owed      3
Waiting             6
System Alerts       1

Important New       5
Read Later          8

Processed quietly   73

The user should be able to understand their workload in seconds.

6. Home Dashboard Sections

Suggested sections:

Needs Me
Waiting on Others
Important New Mail
System Exceptions
Agent Activity
Identity Hygiene

The dashboard should avoid large lists of routine email.

7. Needs Me

This should be the central working view.

It should combine:

ACTION
RESPOND
SYSTEM_ALERT
High-priority unresolved mail
Low-confidence items requiring review

Default sort should emphasize:

Priority
Due date
Age
Human relevance

rather than received timestamp alone.

8. Work Item Presentation

Each item should clearly answer:

Who is this from?
What is it about?
Why am I seeing it?
What do I need to do?
How urgent is it?

Example card:

Jane Smith
Re: Revised Proposal

Respond
High

Jane is asking whether the revised proposal is approved.

Received 2h ago
Professional · jason@jasonkoch.io

9. Work Item Quick Actions

Common actions should be available without opening the full message.

Examples:

Reply
Draft Reply
Mark Done
Move to Waiting
Read Later
Archive
Snooze
Change Priority

Destructive or uncommon actions should not dominate the interface.

10. Conversation-Centric UX

The UI should generally display conversations rather than every individual message as independent work.

A conversation should show:

Participants
Current subject
Last activity
Current attention state
Who owes the next action
Priority
Message count

The latest relevant message should be easy to expand.

11. Conversation Timeline

Opening a conversation should provide a timeline.

Example:

Aug 28
Jane requested revised document.

Aug 29
Jason sent revision.

Sep 1
Jane asked for approval confirmation.

Current state:
RESPOND

The timeline may be partially agent-generated but must remain traceable to actual messages.

12. Agent Context Panel

A conversation should include an Agent panel.

Suggested content:

Summary

Current State
RESPOND

Priority
HIGH

Why
Direct question requiring confirmation.

Suggested Next Step
Reply with approval status.

Waiting?
No

Confidence
High

13. Explainability Interaction

The user should be able to select:

Why?

for any:

Classification
Priority
Attention state
Identity recommendation
Rule execution
Archive action

The explanation should be short and specific.

Example:

I marked this Respond because the sender asked, "Can you confirm the final amount?" and no reply from you appears later in the thread.

14. Manual Correction

Every agent-derived field should be editable where appropriate.

Examples:

Not Action
This is Waiting
Lower Priority
This is Personal
Wrong Project
Keep this sender important

Corrections should be one or two interactions, not a settings workflow.

15. Correction Feedback

After a correction, the UI may say:

Updated.

You've made this correction for this sender 4 times.
Create a rule?

Options:

Create Rule
Not Yet
Never Suggest for This

16. Respond View

The Respond screen should be a focused queue.

Each row/card should show:

Sender
Subject
Summary of requested response
Age
Priority
Mailbox identity

Primary actions:

Draft
Reply
Done
Waiting
Dismiss

17. Draft Experience

When generating a draft, the UI should show:

Original request summary
Generated draft
Target sender
Sending identity
Thread

The sending identity must be explicit.

Example:

From:
jason@jasonkoch.io

This prevents replying from the wrong account or alias.

18. Draft Safety

Generated drafts must never appear to have been sent.

The UI must visually distinguish:

Suggested Draft
Saved Draft
Sent Message

19. Waiting View

Waiting should look like a follow-up queue rather than an inbox.

Example:

Blue Shield Refund

Waiting on:
Customer Service

Last sent:
Aug 29

Waiting:
7 days

Expected:
No explicit date

Suggested:
Follow up

20. Waiting Aging

Waiting items may visually indicate age.

Conceptual states:

Recent
Approaching Follow-Up
Stale
Overdue

Avoid excessive color dependence; text and icons should also communicate state.

21. Follow-Up Action

For stale waiting items, the UI should allow:

Draft Follow-Up
Change Follow-Up Date
Mark Resolved
Dismiss Waiting

22. System Alerts

System alerts should be terse and operational.

Example:

Vercel Deployment Failed

PocketSomm
Production

Failed 18 minutes ago

[View Details]
[Open Original]
[Mark Resolved]

The system mailbox should feel closer to an operations feed than a traditional inbox.

23. System Summary

Routine activity should be collapsed into summaries.

Example:

Today

GitHub
42 successful workflow notifications archived

Vercel
9 successful deployments archived

1 failed deployment requires attention

24. Read Later

The Read Later view should be intentionally calm.

Suggested presentation:

Title / Subject
Sender / Publication
Short summary
Estimated reading value
Received date

Actions:

Open
Archive
Keep
Promote to Action
Dismiss

25. Unified Mail View

The Mail screen should provide traditional mailbox browsing when needed.

Users should be able to choose:

All Mail
Specific account
Specific folder/label
Sent
Drafts
Archive

This is secondary to attention views but still necessary.

26. Mailbox Selector

Mailbox selection should show both purpose and address.

Example:

Personal
jskoch@msn.com

Professional
jason@jasonkoch.io

Commercial
Jason.s.koch@gmail.com

System
platypus.software.dev@gmail.com

Purpose should be more visually prominent than provider.

27. Provider Visibility

Provider should remain visible but secondary.

Example:

Personal
jskoch@msn.com
Microsoft

The user should not need to care about provider mechanics during normal use.

28. Alias Visibility

Messages delivered through an alias should indicate that identity.

Example:

Received as:
jason@jasonkoch.ai

This is especially important when generating replies.

29. Search Experience

Search should accept natural language directly.

Example input:

receipt for my monitor last year

The system may translate this into structured criteria.

The user should be able to inspect or refine those criteria.

30. Search Filters

Search filters should include:

Account
Identity
Sender
Recipient
Date
Attention
Classification
Priority
Has attachment
Project
Historical
Original provider

31. Search Result Presentation

Each result should show:

Subject
Sender
Date
Relevant snippet
Mailbox
Identity
Classification
Historical status if applicable

Search should not obscure where the message physically lives.

32. Natural-Language Command Bar

The application should include a command/search interface capable of both retrieval and action requests.

Examples:

Show what I owe people.

Find all receipts from Apple in 2025.

Archive successful GitHub workflow mail.

Why am I still waiting on this?

Show mail that should probably go to Gmail.

For mutations, the system should preview the operation before execution where appropriate.

33. Command Preview

Example:

Archive successful GitHub workflow notifications

Matched:
1,842 messages

Accounts:
platypus.software.dev@gmail.com

Action:
Archive

[Review Sample]
[Run]
[Cancel]

34. Identity Hygiene Screen

Identity Hygiene should focus on recurring patterns, not individual trivial messages.

Example:

Amazon

Currently received at:
jskoch@msn.com

Suggested:
Jason.s.koch@gmail.com

Volume:
18 messages/month

Reason:
Predominantly shopping and marketing.

35. Identity Recommendation Actions

Actions:

Accept Recommendation
Keep Current Identity
Ignore Sender
Create Rule

Accepting a recommendation should initially mean:

Mark recommendation accepted
Provide guidance

not automatically log into an external service and modify the account.

36. Rules Screen

The Rules screen should be understandable without reading code.

Example:

Archive Successful GitHub Workflows

When:
Sender is github.com
Subject contains "workflow run"
Message indicates success

Then:
Mark read
Archive
Set priority Background

Status:
Active

Matched:
1,847

37. Rule Testing UX

Before enabling a rule:

Test against existing mail

should produce:

Matched:
1,847

Likely correct:
1,842

Needs review:
5

[Review Sample]
[Enable Rule]

38. Review Queue

The Review screen should aggregate uncertainty and approvals.

Possible sections:

Low-Confidence Classification
Suggested Rules
Bulk Actions
Identity Recommendations
Migration Decisions
Deletion Candidates

This avoids scattering approval requests across the product.

39. Approval Card

Example:

Suggested Rule

Archive messages from Retailer X

Reason:
You archived 34 of the last 35 messages.

Would affect:
~8 messages/month

[Approve]
[Modify]
[Reject]

40. Activity Feed

The Activity screen should answer:

What has the agent been doing?

Example:

10:42
Archived 12 successful GitHub notifications

10:40
Classified Blue Shield message as Respond

10:38
Moved conversation to Waiting after your reply

10:33
Suggested identity change for Amazon

41. Undo From Activity

Where reversible:

[Undo]

should be available directly from recent activity.

42. Audit Detail

Activity is a user-friendly view.

Audit is the detailed technical record.

Advanced users should be able to inspect:

Rule ID
Provider operation
Old state
New state
Confidence
Correlation ID
Timestamp

43. Notification Philosophy

The application should not notify for every new message.

Push notifications should be limited to:

CRITICAL
Selected HIGH
User-defined sender alerts
Explicit follow-up reminders

Routine mail belongs in summaries.

44. Mobile UX

The UX must be designed so primary workflows translate cleanly to mobile.

Primary mobile actions:

Review Needs Me
Reply
Approve Draft
Mark Done
Move to Waiting
Archive
Review Alerts
Search

Administrative configuration may remain web-first initially.

45. Future Native iOS Client

The backend and UX model should permit a native iOS application.

A future iOS client may provide:

Unified inbox
Message reading
Thread view
Drafting
Search
Push notifications
Rule approvals
Waiting management
Identity hygiene
Agent interaction

The backend APIs must not assume the only consumer is a Next.js UI.

46. Future Custom Mail Client

If Outlook proves limiting, the Inbox Agent may evolve into the user's primary mail client.

Therefore the domain model should support future traditional mail capabilities such as:

Compose
Reply
Reply All
Forward
Attachments
Drafts
Sent mail
Folder browsing
Message flagging
Read/unread
Delete
Move

These are not all required for the initial Inbox Agent UI.

47. Outlook Coexistence

Initially, Outlook may continue to be used for ordinary mail reading and sending.

The Inbox Agent must tolerate this.

Example:

Jason replies in Outlook.

Inbox Agent should detect the sent reply and update:

RESPOND
→ WAITING

where appropriate.

48. Contact UX Future Boundary

Contact management is not initial scope, but the UI architecture should reserve the concept of:

People

A future People section may support:

Contact search
Deduplication
Merge review
Identity linkage
Source provenance
Preferred email
Relationship notes

49. Contact Display in Mail

Even before full contact consolidation, message views should support a normalized person display where possible.

Example:

Jane Smith

jane@example.com
Known Contact
Professional

instead of presenting only raw addresses.

50. Calendar UX Boundary

The application should not attempt to recreate Fantastical.

Future calendar context may appear inside mail.

Example:

Flight confirmation

This trip appears on your calendar:
Boston
Oct 14–17

The primary calendar interaction remains external.

51. Keyboard Efficiency

The web application should support efficient keyboard operation.

Potential shortcuts:

j / k
Next / previous item

r
Reply

a
Archive

w
Waiting

e
Mark done

/
Search

Exact shortcuts should be configurable and avoid conflicting with browser behavior.

52. Bulk Selection

Users should be able to select multiple messages/conversations.

Bulk actions:

Archive
Mark read
Set classification
Set priority
Dismiss
Create rule from selection

The affected count should always remain visible.

53. Snooze

A user may temporarily defer an item.

Example:

Snooze until:
Tomorrow
Monday
Next week
Custom

Snooze is a visibility state.

It should not alter whether the underlying message remains ACTION or RESPOND.

54. Due Dates

Action and response items should optionally support due dates.

Due dates may come from:

Explicit user entry
Detected message language
External deadline
Agent suggestion

Agent-inferred due dates should be visibly marked as inferred.

55. Priority Editing

Priority should be quickly adjustable.

Example:

Critical
High
Normal
Low
Background

Repeated priority corrections may contribute to rule suggestions.

56. Confidence Visibility

AI confidence should not clutter every screen.

Show it when:

Confidence is low
User asks why
Action is consequential
Message is in Review

High-confidence routine classifications need not display numerical probabilities.

57. Empty States

Empty states should reinforce the attention model.

Example:

You're caught up.

No messages currently need your attention.

Not:

Inbox Zero!

unless that specifically reflects actual message state.

58. Cross-Device State

User state should synchronize across clients.

Examples:

Marked Done on iPhone
→ reflected on web

Rule approved on web
→ active for mobile

Conversation opened in Outlook
→ provider read state eventually reconciled

59. Accessibility

The application should support:

Keyboard navigation
Screen reader semantics
High contrast
Dynamic text where applicable
Accessible focus states
Non-color-only status indicators

Future iOS implementation should support native accessibility conventions.

60. Responsive Design

The web interface should support:

Desktop
Tablet
Mobile browser

without requiring entirely different mental models.

61. Desktop Layout

Suggested desktop layout:

┌──────────────┬──────────────────────┬────────────────────┐
│ Navigation   │ Work / Message List  │ Conversation /     │
│              │                      │ Agent Context      │
│              │                      │                    │
└──────────────┴──────────────────────┴────────────────────┘

This permits fast triage while maintaining context.

62. Mobile Layout

Mobile should use progressive navigation:

Dashboard
   ↓
List
   ↓
Conversation
   ↓
Agent / Actions

Primary actions should remain reachable without complex menus.

63. Visual Priority

Visual prominence should follow:

Critical attention
High-priority action
Human response required
Waiting overdue
Routine mail
Background mail

Do not visually prioritize:

Unread merely because unread
Provider branding
Folder depth
Raw message volume

64. Color Usage

Color may reinforce:

Critical
High
Waiting
System
Background

but status must never depend solely on color.

65. Agent Presence

The AI should feel like an assistant, not a separate chatbot pasted onto the side of a mail application.

Agent interactions should appear contextually:

Summarize
Why?
Draft
What am I waiting for?
Create rule
Find related mail

A general conversational interface may also exist.

66. Conversational Agent

The application may include a persistent command/assistant surface.

Example:

Jason:
Anything important since lunch?

Agent:
Three things need attention:
1. Blue Shield responded...
2. A Vercel deployment failed...
3. Jane Smith needs confirmation...

The conversation should link directly to underlying messages.

67. Agent References

Agent answers should never become disconnected prose.

Every identified message, conversation, alert, or rule should be openable from the response.

68. Summary Drill-Down

Dashboard metrics must be interactive.

Example:

Responses Owed
3

selecting it opens the exact three conversations represented by the count.

69. Daily Brief UX

The Daily Brief should be accessible in-app even if future delivery is also supported via notification or email.

Example:

Morning Brief

Needs you
4

Waiting
6

New important mail
3

System
1 alert

Processed quietly
73

70. Daily Brief Detail

Each section should allow drill-down.

The brief should not require reading a large AI-generated narrative.

Short summaries plus links are preferred.

71. First-Time Setup

Initial setup should be guided.

Suggested flow:

Connect accounts
→ identify mailbox roles
→ identify aliases
→ run read-only inventory
→ show initial findings
→ review automation boundaries
→ enable first rules

72. Account Connection UX

The UI should clearly explain requested access.

Example:

Microsoft Personal

Current access:
Read mail

Requested for organization:
Read + modify mail

Why:
Needed to archive and categorize messages.

Avoid opaque permission prompts whenever the application can explain them beforehand.

73. Automation Level

The user should have a clear control for automation boundaries.

Possible conceptual settings:

Observe
Suggest
Assist
Automate Approved Rules

The application should not present a vague "AI autonomy" slider.

Permissions should remain action-specific.

74. Rule-Level Autonomy

Each rule should specify whether it may:

Suggest only
Execute automatically
Require approval

Example:

Archive successful GitHub notifications
Automatic

Delete old promotions
Approval required

75. Trust-Building UX

Early releases should make agent behavior visible.

Users should be able to see:

What was processed
What changed
Why it changed
What can be undone

As confidence grows, routine low-risk activity may become less prominent.

76. Migration UX

Migration should have a dedicated administrative workflow.

Sections:

Inventory
Folder Mapping
Duplicates
Dry Runs
Migration Runs
Reconciliation
Cleanup

Migration should not be mixed into normal inbox operation.

77. Migration Progress

Example:

iCloud Historical Migration

Processed
12,483 / 18,902

Copied
11,721

Duplicates
721

Review
31

Errors
10

78. Migration Exceptions

Users should be able to review:

Conflicting duplicates
Messages that could not be imported
Unknown destination identity
Attachment failures

without digging through logs.

79. Provider Health UX

Settings or administration should show:

Personal Microsoft
Healthy

Professional Microsoft
Healthy

Commercial Gmail
Healthy

System Gmail
Healthy

iCloud
Read-only / Last sync ...

Unhealthy states should indicate what action is required.

80. Offline / Stale Data

If a provider is unavailable, the UI should explicitly show:

Data may be stale.
Last successful sync: 10:42 AM.

The app should never silently present stale data as current.

81. Error UX

User-facing errors should explain:

What failed
What was affected
Whether anything changed
What the user can do
Whether retry is automatic

Example:

Gmail could not be synchronized. Microsoft mail is unaffected. No Gmail actions were executed.

82. Destructive Action UX

Permanent deletion should require strong confirmation.

The UI should show:

Number of messages
Accounts affected
Whether action is reversible
Why these messages were selected

83. Send UX

If sending is later enabled inside Inbox Agent, sending must always display:

From identity
Recipients
Thread
Draft content
Attachments

The sending identity should never be implicit.

84. Future Contacts Section

A future contact-management interface should likely contain:

People
Duplicates
Merge Review
Sources
Sync Status

The UI should distinguish:

Canonical person
Contact records from providers
Email identities

85. Contact Merge UX

Example future screen:

Jason Smith

Sources:
iCloud
Google
Microsoft

Possible duplicate:
Jason A. Smith

Matching:
Phone
Email
Company

[Merge]
[Keep Separate]
[Review Fields]

86. Contact Field Provenance

For merged contacts, individual fields may retain source information.

Example:

Mobile
(555) 555-1212
Source: iCloud

Work Email
...
Source: Microsoft

This future requirement should influence contact architecture later.

87. Calendar Context

Calendar context should be presented only when relevant.

Examples:

This reservation overlaps an existing calendar event.

This flight appears related to your Boston trip.

This meeting request is already on your calendar.

The UI should deep-link into Fantastical or the underlying calendar where practical rather than recreating calendar management.

88. Scope Boundary

Initial Inbox Agent UI does not need to implement:

Full calendar UI
Full contact editor
Full replacement mail composer
Advanced attachment editor
Multiple-user collaboration

These remain future extensions.

89. UI Acceptance Criteria

The UI satisfies the initial product requirements when: