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

Copy the example config and fill in your credentials:

cp config.toml.example config.toml

Edit config.toml:

[imap]
host     = "imap.gmail.com"   # your provider's IMAP server
port     = 993
username = "you@example.com"
password = "your-password"
use_tls  = true

[smtp]
host     = "smtp.gmail.com"   # your provider's SMTP server
port     = 465
username = "you@example.com"
password = "your-password"
tls_mode = "smtps"            # none | starttls | smtps
from     = "Your Name <you@example.com>"

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 (Bridge)	127.0.0.1	1143	false	127.0.0.1	1025	none
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".

Then run:

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)
password	string	Password or app-specific password
use_tls	bool	true for IMAPS (port 993), false for plain/STARTTLS

[smtp]

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