sander/tuimail
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tuimail/README.md
Shautvast 696c3bec9f doc update
2026-03-02 16:45:37 +01:00

6.6 KiB
Raw Blame History

Tuimail

Tuimail is a terminal email client. It allowes you to use your keyboard to navigate, search and send messages.

Safety features

  • no html rendering (conversion to plain text)
  • no tracking pixels
  • no javascript
  • no local passwords (uses your OS keychain)
  • safe local message storage using AES-256-GCM.
  • safe communication to remote hosts (TLS, PGP for Proton)

Configuring

Sorry, there is no binary release for now. This setup requires that you have rust cargo installed.

Run the setup wizard:

cargo run -- --configure

(the first time --configure is active by default)

When prompted for provider choose imap/proton, choose your provider:

For Imap:

  • IMAP host: imap.gmail.com, port: 993, TLS: true
  • Username
  • Password
  • SMTP host: smtp.gmail.com, port: 465, TLS mode: smtps

Different mail providers may use other hosts and ports.

For Proton (Tuimail does not require the proton-bridge)

  • Username: your proton account user name
  • Password:

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.

Note: every time you recreate the binary file using cargo, macOS will need reapproval for access to the keychain.

Extra Configuration needed for Gmail

1. Enable 2-Step Verification

App Passwords require 2-Step Verification to be enabled on your Google account.

  1. Go to https://myaccount.google.com/security
  2. Under "How you sign in to Google", click 2-Step Verification
  3. Follow the prompts to enable it

2. Create an App Password

  1. Go to https://myaccount.google.com/apppasswords
  2. Enter a name (e.g. "Mail TUI") and click Create
  3. Google will display a 16-character password — copy it

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.