tuimail/USAGE.md

tuimail — User Guide

tuimail is a terminal email client. It shows your inbox in a split-pane view: the email list on top, the message preview on the bottom.

---

Setup

tuimail stores passwords securely in the OS keychain (macOS Keychain, GNOME Keyring, KWallet, Windows Credential Manager). No passwords are ever written to disk in plain text.

First-time setup

Simply run tuimail — if no config file exists it launches an interactive wizard automatically:

cargo run

The wizard prompts for your provider, server settings, and passwords, then saves the config file and stores all passwords in the OS keychain.

Re-configure / update credentials

cargo run -- --configure

All prompts show current values in brackets. Press Enter to keep a value, or type a new one. Password prompts show [stored] when a value already exists in the keychain.

Headless / CI environments (env-var fallback)

If the OS keychain is unavailable, export the passwords as environment variables:

Variable	Credential
TUIMAIL_IMAP_PASSWORD	IMAP password
TUIMAIL_SMTP_PASSWORD	SMTP password
TUIMAIL_PROTON_PASSWORD	ProtonMail login password
TUIMAIL_PROTON_MAILBOX_PASSWORD	ProtonMail mailbox password (two-password mode)

Example:

TUIMAIL_IMAP_PASSWORD=hunter2 cargo run

Common provider settings

Provider	IMAP host	IMAP port	use_tls	SMTP host	SMTP port	tls_mode
Gmail	imap.gmail.com	993	true	smtp.gmail.com	465	smtps
Outlook/Hotmail	outlook.office365.com	993	true	smtp.office365.com	587	starttls
ProtonMail	see ProtonMail section below
Local test server	localhost	143	false	localhost	25	none

Gmail note: You must use an App Password, not your regular password. Enable 2-Step Verification first, then generate an App Password for "Mail".

ProtonMail

tuimail can talk to ProtonMail directly — no separate bridge process needed. The bridge starts automatically in-process when provider = "proton" is set.

1. Build with ProtonMail support:

cargo build --features proton

2. Run the setup wizard:

cargo run --features proton -- --configure

The wizard prompts for your ProtonMail username and password (stored in keychain), two-password mode, and bridge ports. The bridge local password is auto-generated and stored in the keychain.

3. Run:

cargo run --features proton

The bridge authenticates with ProtonMail before the TUI opens. Messages are decrypted on the fly; sent mail is encrypted end-to-end automatically.

Then run (standard providers):

cargo run --release

---

Interface

┌─────────────────────────────────────────────────────┐
│ ▶ Inbox (42 messages)                               │  ← active pane (cyan)
│   2025-01-15 10:32  Alice <alice@example.com>  Hello│
│>> 2025-01-14 09:11  Bob <bob@example.com>      Re: …│  ← selected row
│   2025-01-13 17:44  Carol <carol@example.com>  Mtg  │
├─────────────────────────────────────────────────────┤
│   Message                                           │  ← inactive pane
│                                                     │
│  Hi there,                                         │
│  Just checking in…                                 │
│                                                     │
├─────────────────────────────────────────────────────┤
│  c compose | r reply | / search | q quit | …       │  ← status bar
└─────────────────────────────────────────────────────┘

The active pane is highlighted in cyan with a ▶ prefix. Tab switches focus between the two panes.

---

Keyboard Reference

Navigation

Key	Action
↑ / k	Move up in inbox or scroll message up
↓ / j	Move down in inbox or scroll message down
Tab	Switch focus between inbox list and message preview
q / Esc	Quit (or clear search results)

Scrolling past the last loaded message automatically fetches the next batch of 50 older emails.

Email Actions

Key	Action
r	Reply to the selected email
d	Delete the selected email (moves to Trash)
u / F5	Refresh the inbox manually

Search

Key	Action
/	Open the search bar
(type query)	Filter by subject or sender
Enter	Run the search
Esc	Clear search results and return to inbox

Search runs an IMAP SEARCH OR SUBJECT … FROM … query on the server so it works across your entire mailbox, not just the loaded batch.

Compose

Key	Action
c	Open compose window
r	Open compose pre-filled for replying to the selected email
Tab	Cycle focus: To → Subject → Body → To
Enter	Move to next field (To / Subject); insert newline in Body
Ctrl+S	Send the email
Esc	Cancel and discard the draft

---

Composing and Replying

Press c to compose a new email. The compose window opens full-screen:

┌─ ▶ Compose ──────────────────────┐
│ To:      alice@example.com       │
│ Subject: Hello                   │
├─ Body ───────────────────────────┤
│ Hi Alice,                        │
│                                  │
│ _                                │  ← cursor
└──────────────────────────────────┘
 Ctrl+S send | Esc cancel | Tab switch field

Press r to reply. The compose window opens with:

• To pre-filled with the sender's address
• Subject set to Re: <original subject>
• Cursor placed in the Body field, ready to type
• The original message shown below a separator (dimmed) — included in the sent email automatically

┌─ ▶ Compose ──────────────────────┐
│ To:      bob@example.com         │
│ Subject: Re: Weekend plans       │
├─ Body ───────────────────────────┤
│ _                                │  ← type your reply here
│ ─────────────────────────────── │
│ On 2025-01-14 09:11, Bob wrote: │
│ > Are you free Saturday?         │
└──────────────────────────────────┘

If the message body hasn't finished loading when you press r, the quote is omitted. Press Esc, wait a moment for the preview to appear, then press r again.

---

Auto-refresh

The inbox refreshes automatically every 30 seconds in the background. A [loading…] indicator appears in the inbox title while a refresh is in progress. Your current selection is preserved across refreshes.

---

Configuration Reference

[imap]

Key	Type	Description
host	string	IMAP server hostname
port	integer	IMAP port (usually 993 with TLS, 143 without)
username	string	Login username (usually your full email address)
use_tls	bool	true for IMAPS (port 993), false for plain/STARTTLS

Password is stored in the OS keychain. Use --configure to set or update it.

[smtp]

Key	Type	Description
host	string	SMTP server hostname
port	integer	SMTP port
username	string	Login username
tls_mode	string	none, starttls, or smtps
from	string	Sender address shown to recipients, e.g. Name <addr>

Password is stored in the OS keychain. Use --configure to set or update it.