# simplemailclient
A small terminal mail client written in Rust. It sends mail over SMTP, fetches
over IMAP, and gives you a split-pane TUI for reading, replying, and composing.
The installed binary is named **`mailrs`** (avoids clashing with the standard
Unix `mail` command).
## Features
- **TUI inbox** — folders (Inbox / Sent / Starred / Trash), a message list, and
a reading pane, navigable with `Tab` / arrow keys and `j` / `k`.
- **Compose & reply** in-app: To / Body / Attach fields, `Ctrl+S` to send,
`Esc` to cancel.
- **File attachments** — attach any file type up to 25 MB (zip, images, PDFs,
text, …). Each file is sent as its own MIME part, fully separate from the
message body. On received mail, attachments are listed below the body; focus
the reading pane, pick one with `↑`/`↓`, press `Enter` to preview text files
inline, or `Ctrl+A` to save to your Downloads folder.
- **Inline text preview** — `Enter` on any text attachment (.txt, .md, .json,
.csv, source files, …) opens a scrollable full-screen viewer. `Esc` to close.
- **Real trash** — `d` moves the message locally *and* copies it to the
configured trash folder on the IMAP server, then expunges it from the inbox
so it never comes back on re-sync.
- **New-mail bell** — a terminal beep fires when a sync brings in unread mail.
- **Deduplication** — messages are keyed by their RFC 2822 `Message-ID`; a
message you've already seen is never re-delivered on sync.
- **Auto-sync** every 10 seconds while idle, plus on-demand sync with `S`.
Fetches up to the last 50 messages.
- **Contacts** — auto-collected from every address you send to or receive from.
Press `?` to open the contacts panel (it gets focus automatically), where you
can add entries manually, delete them, and set a short **nickname** (alias).
In the compose To field, address someone by their numeric ID, nickname, bare
username, or full address.
## Install
```sh
cargo install simplemailclient
```
## Configuration
On first run a starter config is written to your config directory
(`~/.config/mail-rs/config.toml` on Linux/macOS,
`%APPDATA%\mail-rs\config.toml` on Windows). Fill in your SMTP/IMAP details:
```toml
identity = "you@gmail.com"
display_name = "Your Name"
domain = "gmail.com"
[smtp]
host = "smtp.gmail.com"
port = 587
username = "you@gmail.com"
password = "your-app-password" # use an App Password, not your login password
tls = true
[imap]
host = "imap.gmail.com"
port = 993
username = "you@gmail.com"
password = "your-app-password"
tls = true
inbox_folder = "INBOX"
trash_folder = "[Gmail]/Trash" # Gmail; other providers: "Trash" or "Deleted"
```
> **Gmail users**: `trash_folder` must be `[Gmail]/Trash`.
> **Other providers**: try `Trash` (the default) or `Deleted`.
## Usage
```sh
mailrs # launch the interactive TUI
mailrs read <index> # read a message by index
mailrs sync # fetch new mail via IMAP
```
### TUI keys
| `Tab` / `←→` | Move focus between panes |
| `↑↓` / `j` `k` | Navigate list / attachments |
| `Enter` | Open message · preview selected text attachment |
| `c` | Compose new message |
| `r` | Reply to the open message |
| `s` | Star / unstar |
| `d` | Move to trash (local + IMAP server) |
| `Ctrl+A` | Save selected attachment to Downloads |
| `S` | Sync now |
| `?` | Open / close contacts panel |
| `q` | Quit |
### Contacts panel (`?`)
Pressing `?` opens the panel and immediately focuses it — no extra `Tab` needed.
| `↑↓` / `j` `k` | Navigate the contact list |
| `a` | Add a contact manually |
| `d` | Delete the selected contact |
| `n` | Set / edit / clear the nickname |
| `Tab` | Move focus to the message list |
| `?` | Close the panel |
### Compose modal
`Tab` cycles **To → Body → Attach → Body**.
The **To** field accepts any of:
- a full address — `alice@example.com`
- a bare username — `alice` (appended with your configured `domain`)
- a numeric contact ID — `3`
- a **nickname** — `ally` (if set for that contact)
In the **Attach** field, type a file path and press `Enter` to queue it.
Backspace on an empty input removes the last queued file.
`Ctrl+S` sends; `Esc` cancels.
### Attachment viewer
`Enter` on a selected attachment (reading pane) opens an inline viewer for any
UTF-8 text file. Use `↑↓` / `j` / `k` to scroll, `PgUp` / `PgDn` for larger
jumps, and `Esc` or `q` to close. Binary files (images, zips, etc.) show an
error and prompt you to use `Ctrl+A` to save instead.
## Data
Mail and contacts are stored locally:
| Linux / macOS | `~/.local/share/mail-rs/mailbox.json` |
| Windows | `%LOCALAPPDATA%\mail-rs\mailbox.json` |
Configuration lives in:
| Linux / macOS | `~/.config/mail-rs/config.toml` |
| Windows | `%APPDATA%\mail-rs\config.toml` |
## License
[MIT](LICENSE)