read timer and fix update UI when mark as read on server

Author: sspaeti

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+# 2026-04-17
+- **Timer-based mark-as-read** — emails are no longer marked as read immediately when opened; instead, a configurable timer (default 7 seconds) starts when you enter the reader; if you stay for the full duration, the email is marked as `\Seen`; if you exit early (quick peek), it stays unread; prevents accidental marking when browsing through emails
+- **`mark_as_read_after_secs` config** — new `[ui]` option to control mark-as-read delay in seconds (default 7); set to `0` for immediate marking (old behavior); set to any value to customize the delay
+- **Fix: local UI state sync on mark-as-read** — inbox list now updates immediately when an email is marked as read, either via timer or manual toggle (`n`); previously the server was updated but the local UI showed stale unread indicators until manual refresh
+
 # 2026-04-16
 - **`B` move to Work/business** — press `B` to move marked or cursor email(s) to Work folder (similar to `A` for Archive); quick single-key action without screener list updates; shows friendly error if Work folder not configured; useful for rapid GTD-style email processing; complements existing `gb` (go to Work) and `Mb` (move to Work) shortcuts
 - **Redesigned welcome screen** — new two-column layout with ASCII art logo, philosophy/getting started guide on the left, and essential shortcuts organized by category on the right; wider box (100 chars) with cleaner spacing; maintains kanagawa color scheme; more scannable and visually appealing for new users

README.md

@@ -50,7 +50,7 @@ flowchart TD
     Inbox --> Process{Process Email<br/>GTD Decision}
 
     Process -->|< 2 min?<br/>Do it now| Action[Reply/Handle<br/>Immediately]
-    Process -->|Waiting for others<br/>Press mW| Waiting[⏳ Waiting]
+    Process -->|Waiting for others<br/>Press Mw| Waiting[⏳ Waiting]
     Process -->|Not now, later<br/>Press Mm| Someday[📅 Someday]
     Process -->|Time-specific<br/>Press Mc then c| Scheduled[🗓️ Scheduled]
     Process -->|Delete<br/>Press x| Trash[🗑️ Trash]
@@ -72,7 +72,7 @@ flowchart TD
     classDef folderStyle fill:#54546d,stroke:#7fb4ca,stroke-width:2px,color:#dcd7ba
     class ToScreen,Inbox,ScreenedOut,Feed,PaperTrail,Archive,Waiting,Someday,Scheduled,Trash folderStyle
 ```
-*Styled with Kanagawa colors - all boxes represent neomd folders*
+*all colored boxes represent neomd folders*
 
 **Key principles:**
 - **Screener first**: Unknown senders never clutter your Inbox — they wait in ToScreen for classification

docs/content/docs/_index.md

@@ -25,12 +25,70 @@ Also, we intentionally don't add more folders to the archive or file emails too,
 
 But we have two additional **Feed** and **Papertrail**, two dedicated folders from HEY where you can read newsletters (just hit F) on them automatically in their separate tab, or move all your receipts into the Papertrail. Once you mark them as feed or papertrail, they will moved there automatically going forward. So you decide whether to read emails or news by jumping to different tabs.
 
-
 {{< callout type="info" >}}
 neomd's **speed** depends entirely on your IMAP provider. On Hostpoint (the provider I use), a folder switch takes **~33ms** which feels instant. On Gmail, the same operation takes **~570ms** which is noticeably slow. See [Benchmark](#benchmark) for full details and how to test your provider.
 {{< /callout >}}
 
 
+### Email Processing Workflow
+
+Here's how neomd combines HEY-Screener + GTD + Feed/Papertrail to process your email:
+
+```mermaid
+flowchart TD
+    Start([New Email Arrives]) --> AutoScreen{Auto-Screener<br/>Known Sender?}
+
+    AutoScreen -->|screened_in.txt| Inbox["📥 Inbox (Next)"]
+    AutoScreen -->|screened_out.txt| ScreenedOut[🚫 ScreenedOut]
+    AutoScreen -->|feed.txt| Feed[📰 Feed]
+    AutoScreen -->|papertrail.txt| PaperTrail[🧾 PaperTrail]
+    AutoScreen -->|Unknown| ToScreen[❓ ToScreen]
+
+    ToScreen -->|Press I| ClassifyIn[Add to screened_in.txt]
+    ToScreen -->|Press O| ClassifyOut[Add to screened_out.txt]
+    ToScreen -->|Press F| ClassifyFeed[Add to feed.txt]
+    ToScreen -->|Press P| ClassifyPaper[Add to papertrail.txt]
+
+    ClassifyIn --> Inbox
+    ClassifyOut --> ScreenedOut
+    ClassifyFeed --> Feed
+    ClassifyPaper --> PaperTrail
+
+    Inbox --> Process{Process Email<br/>GTD Decision}
+
+    Process -->|< 2 min?<br/>Do it now| Action[Reply/Handle<br/>Immediately]
+    Process -->|Waiting for others<br/>Press Mw| Waiting[⏳ Waiting]
+    Process -->|Not now, later<br/>Press Mm| Someday[📅 Someday]
+    Process -->|Time-specific<br/>Press Mc then c| Scheduled[🗓️ Scheduled]
+    Process -->|Delete<br/>Press x| Trash[🗑️ Trash]
+    Process -->|Reference only<br/>Press Mp or P| PaperTrail
+    Process -->|Newsletter<br/>Press F or Mf| Feed
+
+    Action --> Done{Done?}
+    Waiting --> Review[Review Later]
+    Someday --> Review
+    Scheduled --> Review
+    Feed --> ReadLater[Read in<br/>Feed Tab]
+    PaperTrail --> SearchLater[Search when<br/>needed]
+
+    Done -->|Yes| Archive[📦 Archive]
+    Done -->|Not actionable| Archive
+    Review --> Archive
+    ReadLater --> Archive
+
+    classDef folderStyle fill:#54546d,stroke:#7fb4ca,stroke-width:2px,color:#dcd7ba
+    class ToScreen,Inbox,ScreenedOut,Feed,PaperTrail,Archive,Waiting,Someday,Scheduled,Trash folderStyle
+```
+*all colored boxes represent neomd folders*
+
+**Key principles:**
+- **Screener first**: Unknown senders never clutter your Inbox — they wait in ToScreen for classification
+- **One-time decision**: Once you classify a sender (`I/O/F/P`), all future emails from them are automatically routed
+- **GTD processing**: Emails in Inbox are processed once — if < 2 min, do it or keep it in inbox as doing *Next* otherwise move to Waiting, Someday, or Scheduled
+- **Minimal filing**: Only Archive when done; no complex folder hierarchies — use search to find old emails
+- **Separate contexts**: Feed for newsletters (read when you want), PaperTrail for receipts (search when needed)
+
+
 ## Screenshots
 
 ### Overview: List-View

docs/content/docs/configuration.md

@@ -76,6 +76,7 @@ auto_screen_on_load  = true     # screen inbox automatically on every load (defa
 bg_sync_interval     = 5        # background sync interval in minutes; 0 = disabled (default 5)
 bulk_progress_threshold = 10    # show progress counter for batch operations larger than this (default 10)
 draft_backup_count      = 20    # rolling compose backups in ~/.cache/neomd/drafts/ (default 20, -1 = disabled)
+mark_as_read_after_secs = 7     # seconds in reader before marking as read; 0 = immediate (default 7)
 signature   = """**Your Name**
 Your Title, Your Company
 

docs/content/docs/reading.md

@@ -103,6 +103,34 @@ Results display in a temporary "Thread" tab:
 
 Also available as `:thread` (alias `:t`) from the command line.
 
+## Mark as Read Behavior
+
+Neomd marks emails as read **after you've spent time viewing them**, not immediately when opened. This prevents accidental marking when quickly peeking at emails.
+
+**How it works:**
+
+- When you open an email (press `enter` or `l`), neomd fetches the full body from IMAP
+- Once the body loads, a **timer starts** (default: 7 seconds)
+- If you stay in the reader for the full duration, the email is marked as `\Seen` on the server
+- If you exit early (press `h`, `q`, `esc`, or `T`), the email **stays unread**
+
+**Configuration:**
+
+```toml
+[ui]
+mark_as_read_after_secs = 7   # wait 7 seconds (default)
+# mark_as_read_after_secs = 0   # immediate marking (no timer)
+# mark_as_read_after_secs = 10  # 10 seconds
+```
+
+Set to `0` for immediate marking (as soon as the body finishes loading). Set to any value in seconds to customize the delay.
+
+**UI behavior:**
+
+- The local inbox list updates immediately when an email is marked as read — no need to manually refresh
+- The unread indicator (`N`) disappears as soon as marking completes
+- Manual toggle with `n` still works to mark/unmark emails at any time
+
 ## Reply Indicator
 
 Emails you've replied to show a `·` dot in the inbox list. This uses the standard IMAP `\Answered` flag, so it works across clients — if you reply from webmail, neomd shows it too.

internal/config/config.go

@@ -134,6 +134,7 @@ type UIConfig struct {
 	BgSyncInterval        int              `toml:"bg_sync_interval"`        // background sync interval in minutes (0 = disabled, default 5)
 	BulkProgressThreshold int              `toml:"bulk_progress_threshold"` // show progress counter for batches larger than this (default 10)
 	DraftBackupCount      int              `toml:"draft_backup_count"`      // rolling compose backups in ~/.cache/neomd/drafts/ (default 20, -1 = disabled)
+	MarkAsReadAfterSecs   int              `toml:"mark_as_read_after_secs"` // seconds in reader before marking as read (0 = immediate, default 7)
 }
 
 // TextSignature returns the text/markdown signature for editor and text/plain part.
@@ -360,10 +361,11 @@ func defaults() *Config {
 			Spam:        "Spam",
 		},
 		UI: UIConfig{
-			Theme:          "dark",
-			InboxCount:     200,
-			BgSyncInterval: 5,
-			Signature:      "*sent from [neomd](https://neomd.ssp.sh)*",
+			Theme:               "dark",
+			InboxCount:          200,
+			BgSyncInterval:      5,
+			MarkAsReadAfterSecs: 7,
+			Signature:           "*sent from [neomd](https://neomd.ssp.sh)*",
 		},
 	}
 }

internal/integration_test.go

@@ -664,6 +664,89 @@ func TestIntegration_ReplyAllPreservesRecipients(t *testing.T) {
 	t.Logf("Reply-all delivered: To=%s CC=%s", reply.To, reply.CC)
 }
 
+func TestIntegration_MarkAsRead(t *testing.T) {
+	env := loadEnv(t)
+	cli := env.imapClient()
+	defer cli.Close()
+
+	subject := uniqueSubject("mark-as-read")
+	body := "Testing mark-as-read functionality."
+
+	// Send test email to self
+	err := smtp.Send(env.smtpConfig(), env.user, "", "", subject, body, nil)
+	if err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	// Wait for delivery
+	email := waitForEmail(t, cli, "INBOX", subject, 30*time.Second)
+	defer cleanupEmail(t, cli, "INBOX", email.UID)
+
+	// Initially unread
+	if email.Seen {
+		t.Error("newly delivered email should be unread (Seen=false)")
+	}
+
+	// Mark as seen
+	ctx := context.Background()
+	err = cli.MarkSeen(ctx, "INBOX", email.UID)
+	if err != nil {
+		t.Fatalf("MarkSeen: %v", err)
+	}
+
+	// Re-fetch to verify flag changed
+	emails, err := cli.FetchHeaders(ctx, "INBOX", 20)
+	if err != nil {
+		t.Fatalf("FetchHeaders after MarkSeen: %v", err)
+	}
+
+	var found *goIMAP.Email
+	for i := range emails {
+		if emails[i].UID == email.UID {
+			found = &emails[i]
+			break
+		}
+	}
+
+	if found == nil {
+		t.Fatal("email not found after MarkSeen")
+	}
+
+	if !found.Seen {
+		t.Error("email still unread after MarkSeen call")
+	}
+
+	// Test MarkUnseen
+	err = cli.MarkUnseen(ctx, "INBOX", email.UID)
+	if err != nil {
+		t.Fatalf("MarkUnseen: %v", err)
+	}
+
+	// Re-fetch to verify flag cleared
+	emails, err = cli.FetchHeaders(ctx, "INBOX", 20)
+	if err != nil {
+		t.Fatalf("FetchHeaders after MarkUnseen: %v", err)
+	}
+
+	found = nil
+	for i := range emails {
+		if emails[i].UID == email.UID {
+			found = &emails[i]
+			break
+		}
+	}
+
+	if found == nil {
+		t.Fatal("email not found after MarkUnseen")
+	}
+
+	if found.Seen {
+		t.Error("email still marked as read after MarkUnseen call")
+	}
+
+	t.Logf("Mark-as-read round-trip successful: UID=%d", email.UID)
+}
+
 // --- Helpers ---
 
 func extractUser(from string) string {

internal/ui/model.go

@@ -112,6 +112,11 @@ type (
 	bgSyncTickMsg     struct{}
 	bgInboxFetchedMsg struct{ emails []imap.Email }
 	bgScreenDoneMsg   struct{ moved, total int }
+	// mark-as-read timer (fires after N seconds in reader)
+	markAsReadTimerMsg struct {
+		uid    uint32
+		folder string
+	}
 	// attachPickDoneMsg carries paths selected via the file picker (yazi etc.)
 	attachPickDoneMsg struct{ paths []string }
 	// bulkProgressMsg is sent during long-running batch operations to update the status bar.
@@ -450,6 +455,9 @@ type Model struct {
 	openAttachments []imap.Attachment // attachments of the currently open email
 	openLinks       []emailLink       // extracted links from the email body
 	readerPending   string            // chord prefix in reader (space for link open)
+	// Mark-as-read timer tracking
+	markAsReadUID    uint32 // UID of email with pending mark-as-read timer
+	markAsReadFolder string // folder of email with pending mark-as-read timer
 
 	// Compose / pre-send
 	compose      composeModel
@@ -1434,6 +1442,18 @@ func (m Model) scheduleBgSync() tea.Cmd {
 	return tea.Tick(time.Duration(mins)*time.Minute, func(time.Time) tea.Msg { return bgSyncTickMsg{} })
 }
 
+// scheduleMarkAsReadTimer returns a Cmd that fires markAsReadTimerMsg after the configured
+// delay. Returns nil (no-op) when mark_as_read_after_secs = 0 (immediate marking).
+func (m Model) scheduleMarkAsReadTimer(uid uint32, folder string) tea.Cmd {
+	secs := m.cfg.UI.MarkAsReadAfterSecs
+	if secs <= 0 {
+		return nil // immediate marking handled elsewhere
+	}
+	return tea.Tick(time.Duration(secs)*time.Second, func(time.Time) tea.Msg {
+		return markAsReadTimerMsg{uid: uid, folder: folder}
+	})
+}
+
 // bgFetchInboxCmd silently fetches inbox headers for background screening.
 // Errors are swallowed — a transient network hiccup shouldn't disrupt the UI.
 func (m Model) bgFetchInboxCmd() tea.Cmd {
@@ -1641,10 +1661,24 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if msg.email != nil {
 			msg.email.References = msg.references
 		}
-		// Mark as seen in background (best-effort)
+		// Mark as seen: either immediately (if config = 0) or after timer
 		uid := msg.email.UID
 		folder := msg.email.Folder
-		go func() { _ = m.imapCli().MarkSeen(nil, folder, uid) }()
+		if m.cfg.UI.MarkAsReadAfterSecs <= 0 {
+			// Immediate marking (config = 0)
+			go func() { _ = m.imapCli().MarkSeen(nil, folder, uid) }()
+			// Update local state immediately
+			for i := range m.emails {
+				if m.emails[i].UID == uid && m.emails[i].Folder == folder {
+					m.emails[i].Seen = true
+					break
+				}
+			}
+		} else {
+			// Schedule timer-based marking
+			m.markAsReadUID = uid
+			m.markAsReadFolder = folder
+		}
 		if m.pendingForward {
 			m.pendingForward = false
 			return m.launchForwardCmd()
@@ -1664,6 +1698,10 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		m.openLinks = extractLinks(msg.body)
 		_ = loadEmailIntoReader(&m.reader, msg.email, msg.body, msg.attachments, m.openLinks, m.cfg.UI.Theme, m.width)
 		m.state = stateReading
+		// Start mark-as-read timer if configured
+		if m.cfg.UI.MarkAsReadAfterSecs > 0 {
+			return m, m.scheduleMarkAsReadTimer(uid, folder)
+		}
 		return m, nil
 
 	case sendDoneMsg:
@@ -1744,6 +1782,26 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		}
 		return m, m.applyFilter()
 
+	case markAsReadTimerMsg:
+		// Timer fired - mark email as read if user is still viewing it
+		if m.state == stateReading && m.markAsReadUID == msg.uid && m.markAsReadFolder == msg.folder {
+			// Still viewing the same email - mark it as read
+			go func() { _ = m.imapCli().MarkSeen(nil, msg.folder, msg.uid) }()
+			// Update local state immediately
+			for i := range m.emails {
+				if m.emails[i].UID == msg.uid && m.emails[i].Folder == msg.folder {
+					m.emails[i].Seen = true
+					break
+				}
+			}
+			// Clear timer state
+			m.markAsReadUID = 0
+			m.markAsReadFolder = ""
+			return m, m.applyFilter()
+		}
+		// User navigated away - ignore timer
+		return m, nil
+
 	case imapSearchResultMsg:
 		return m.handleIMAPSearchResult(msg)
 
@@ -2879,6 +2937,9 @@ func (m Model) updateReader(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	case "q", "esc", "h":
 		m.state = stateInbox
 		m.readerPending = ""
+		// Clear mark-as-read timer state when exiting reader
+		m.markAsReadUID = 0
+		m.markAsReadFolder = ""
 		return m, nil
 	case "e":
 		return m.openInNeovim()
@@ -2914,6 +2975,9 @@ func (m Model) updateReader(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		if m.openEmail != nil {
 			m.loading = true
 			m.state = stateInbox
+			// Clear mark-as-read timer state when switching to conversation view
+			m.markAsReadUID = 0
+			m.markAsReadFolder = ""
 			return m, tea.Batch(m.spinner.Tick, m.fetchConversationCmd(m.openEmail))
 		}
 	case "1", "2", "3", "4", "5", "6", "7", "8", "9":