# 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: ```bash 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 ```bash 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: ```bash 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](https://myaccount.google.com/apppasswords), > 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:** ```bash cargo build --features proton ``` **2. Run the setup wizard:** ```bash 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:** ```bash 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): ```bash cargo run --release ``` --- ## Interface ``` ┌─────────────────────────────────────────────────────┐ │ ▶ Inbox (42 messages) │ ← active pane (cyan) │ 2025-01-15 10:32 Alice Hello│ │>> 2025-01-14 09:11 Bob Re: …│ ← selected row │ 2025-01-13 17:44 Carol 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: ` - **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 ` | > Password is stored in the OS keychain. Use `--configure` to set or update it.