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:

```bash
cp config.toml.example config.toml
```

Edit `config.toml`:

```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](https://myaccount.google.com/apppasswords),
> not your regular password. Enable 2-Step Verification first, then generate an
> App Password for "Mail".

Then run:

```bash
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>` |