tidemail

README

TideMail

Mail for people who live in a terminal.

TideMail keeps your accounts, message list, and reading pane on one screen. It speaks IMAP and SMTP, stores its cache on your machine, and gives the keyboard the good seat.

Need the full settings and shortcut reference? Open the setup and usage guide.

One inbox, several built-in themes.

Highlights

• NO config file editing, all in the GUI.
• One view for every account. Read a unified inbox or open any account, folder, or label from the same three-pane screen.
• Send from the right address. Pick an account from the compose From row. TideMail switches its SMTP settings, Drafts folder, From address, and signature with it.
• Mail state stays in sync. Read state, stars, archive, move, and delete use IMAP. Changes made in Gmail or another client return to TideMail on sync.
• A few seconds to change your mind. Press Ctrl+Z to stop a queued send or undo a pending delete, archive, or move.
• An outbox you can trust. Press O to inspect queued, sending, failed, and sent mail. Failed deliveries survive restarts and can be retried or edited.
• Unsubscribe without hunting for a footer. Press Ctrl+U while reading to use the message's unsubscribe header or labeled unsubscribe link.
• Compose your way. The standard editor supports text selection, the system clipboard, undo and redo, and word movement. You can switch on Vim motions and commands instead. Optional AI tools can summarize mail, proofread a draft, and build local filters from plain English.
• Readable by design, in every theme. Text, selection highlights, and the focused-pane border are all checked against WCAG-style contrast minimums (4.5:1 for text, 3:1+ for large text and UI elements like borders) across every built-in theme, enforced by automated tests.
• Match your desktop. On Omarchy, the match-omarchy theme follows your current desktop theme — contrast-corrected to the same bar as the built-ins — and repaints live when you switch it.

Install

Linux and macOS builds are available for Intel and ARM machines.

Arch Linux

TideMail is on the AUR as tidemail-bin, which packages the official release binary:

yay -S tidemail-bin
# or
paru -S tidemail-bin

Updates come from your AUR helper — yay -Syu or paru -Syu alongside everything else, or yay -S tidemail-bin for just this one. Plain pacman -Syu will not do it: pacman skips packages it did not install from a sync repo, so it reports success and leaves TideMail where it was. TideMail notices it was installed this way and points you at the right command instead of trying to replace a root-owned binary itself.

Everywhere else

curl -fsSL https://raw.githubusercontent.com/allisonhere/tidemail/main/install.sh | sh

The installer writes to ~/.local/bin by default, so it should not ask for a system password. Set INSTALL_DIR=/path/to/bin on the sh command if you want a different writable destination. If an older tidemail earlier on PATH would still run first, the installer removes it when possible or prints the exact cleanup command.

You can also grab an archive from the latest release.

One screen, three useful panes

The left pane holds accounts and folders. The upper-right pane shows the current message list. The reading pane stays below it, so opening a message never hides the rest of your inbox.

Use j and k to move. Press Tab to cross panes. Hit ? whenever you forget a key. TideMail keeps the help screen inside the app and lets you search it.

A normal day in TideMail

• Rest on a folder to refresh a stale cache silently, press Enter or s to fetch it immediately, or press F to sync every folder.
• Mark messages with Space, then archive, move, delete, or change read state as a group.
• Press / to search the local message cache across accounts.
• Use * for a server-backed star. The next sync picks up star changes from Gmail and other clients.
• Open a message and press r to reply, f to forward, or Ctrl+U to use its unsubscribe header.

Delete, archive, and move wait six seconds before TideMail sends them to the server. Ctrl+Z restores the last queued action.

Compose with the right account

The From row becomes an account picker when you have more than one sender. TideMail uses the chosen account for SMTP, drafts, the From address, and its signature. Replies, forwards, and reopened drafts use the same picker.

To, CC, and BCC suggest saved contacts first. TideMail follows with addresses found in mail you have synced. You can manage contacts in the app and move them through vCard files.

TideMail saves the draft while you type. A sent message waits five seconds by default, which gives Ctrl+Z time to reopen it. Set the delay to 0 if you want mail to leave at once. Failed sends retry up to three total attempts by default; change the limit under Settings → Editor. Set it to 1 to disable retries.

The standard compose editor supports Shift-selection, clipboard shortcuts, undo and redo, word movement, and Home/End. Turn Vim mode on in Settings if you prefer commands such as dw, dd, :w, and :q.

Mail state belongs to the server

Read state, stars, archive, move, and delete sync through IMAP. TideMail keeps a local SQLite cache for speed and search, then reconciles it with the server on sync. By default an account uses IMAP IDLE, so mail lands as the server announces it (sync_minutes = 0); interval polling stays available for servers that need it, and -1 keeps an account manual-only.

Drafts live under the selected sender account. Sent messages use that account's SMTP settings and are filed in its server-side Sent folder; Gmail's own SMTP filing is detected so it does not receive a duplicate. TideMail detects common Sent, Archive, and Trash folder names, including Gmail labels.

Search, links, and attachments

Global search stays active while you move through results. The content pane can find text inside the open message, walk links, copy a visual selection, and save attachments to a folder you choose.

TideMail renders HTML mail as terminal text and does not load remote images. Full headers are one Ctrl+E away, with SPF, DKIM, and DMARC results called out in color.

Optional AI tools

Connect OpenAI, Claude, Gemini, or a local Ollama server if you want message summaries and a compose proofread. TideMail can also turn a plain-language mail rule into a local filter that runs without an AI call for each message.

AI stays off until you configure a provider.

Keys worth learning

Key	Action
j / k	Move down or up
Tab / Shift+Tab	Move between panes or compose fields
Enter	Open a message, immediately sync a folder, or open a draft or picker
c	Compose
r / f	Reply or forward from the reading pane
Space	Select a message for a bulk action
a / m / d	Archive, move, or delete
x	Toggle read state for selected messages
*	Toggle the IMAP star
/	Search messages
Ctrl+Z	Cancel a queued send or undo a queued message action
O	Open the Outbox
Ctrl+U	Unsubscribe while reading; cycle sender while composing
Alt+F / Ctrl+R	Attach a file while composing; remove the last attachment
Ctrl+D	Save attachments from the open message
Ctrl+E	Show or hide full headers
M / S / T	Accounts, settings, or themes
Space in Accounts	Mark the highlighted account ★ [default] — the sender for new messages
Shift+J / Shift+K in Accounts	Move the highlighted account down or up the list
: / Ctrl+P	Command palette
?	Searchable help
q	Quit

First account

Press M, add your incoming and outgoing mail settings, then save with Ctrl+S. Gmail, Yahoo, and iCloud require an app password; Gmail and Outlook can sign in with OAuth instead (see below). Any other IMAP/SMTP server — including an on-premises Microsoft Exchange server — uses the Custom provider with a username and password.

TideMail stores passwords, AI keys, and OAuth refresh tokens in libsecret on Linux or Keychain on macOS. If secret-tool is missing on Linux, TideMail falls back to ~/.config/tidemail/config.toml, so protect that file.

Gmail with OAuth

Official TideMail builds include a Google Desktop app registration. Users do not need Google Cloud credentials, environment variables, or config-file edits.

1. Press M → add account → provider Gmail, and enter your account details.
2. Leave Auth on OAuth and press Ctrl+O (or Enter on Sign in with Google).
3. Approve access in your browser. TideMail receives the result automatically; return to TideMail and save with Ctrl+S.

If the browser cannot open, TideMail shows a sign-in URL and manual entry steps. For SSH use, press Ctrl+P while waiting for browser approval, open the displayed URL on your own computer, and paste the full redirect URL into the Code field. A connection error at that redirect is expected when using another computer. Press Enter to finish, then Ctrl+S to save. Esc cancels an attempt; attempts expire after five minutes.

Refresh tokens use the existing keychain storage (with the config-file fallback described above) and refresh access for IMAP and SMTP. If access expires or is revoked, open the account with M and press Ctrl+O again. Existing app-password accounts keep their authentication method; the Auth selector still offers App password.

Maintainers and source-build developers: see Google OAuth registration and release setup. A source build without credentials explains that Google sign-in is unavailable; official release builds reject missing credentials before publishing.

Outlook

Provider Outlook covers Outlook.com, Hotmail, and Microsoft 365 / Exchange Online. Microsoft dropped basic auth for these, so the account signs in with OAuth — but it needs no setup: TideMail uses Thunderbird's shared public client. Add the account, keep the Auth row on OAuth, press Ctrl+O, open the copied URL, approve, and paste the https://localhost/?code=… URL the browser lands on into the Code field. Set TIDEMAIL_MS_CLIENT_ID to your own Azure app to get the device-code flow instead. M365 work/school mailboxes need IMAP enabled by an admin (Set-CASMailbox -ImapEnabled $true).

On-premises Exchange Server

A self-hosted Exchange server (2016/2019/SE) is not the Outlook provider — it does not use Microsoft's cloud sign-in. Use the Custom provider with your server's IMAP/SMTP hostname and your normal username and password; on-prem Exchange still accepts basic auth over TLS. TideMail cannot connect to an on-prem server that has disabled basic auth and requires NTLM or Kerberos (GSSAPI).

theme = "lavender-fields-forever"
# The account new messages are sent from, and the one focused at startup.
# Holds an account id, so renaming or reordering never moves it. Omit it and
# TideMail uses the first account below. Set it with Space in Accounts.
default_account = "8f43c9e644384bd5a25a27ff0d9c2701"

[display]
send_delay_seconds = 5
send_max_attempts = 3  # total attempts; 1 disables automatic retries
compose_vim = true

[[account]]
id = "8f43c9e644384bd5a25a27ff0d9c2701" # generated by TideMail; do not copy or edit
name = "Personal"
imap_host = "imap.example.com"
imap_port = 993
imap_tls = true
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_tls = true
user = "mira@example.com"
from = "Mira Chen <mira@example.com>"  # optional, but a name alone is not an address
signature = """
Mira
Sent with TideMail"""
sync_minutes = 0  # push via IMAP IDLE; N polls every N min, -1 is manual only

The signature is a multi-line box in the account form, so Enter gives you a new line and there is no escape to remember; editing the file by hand works too, and a TOML multi-line string is easier to read than \n escapes.

The order of the [[account]] blocks is the order accounts appear everywhere: the sidebar, the account list, and the Ctrl+U sender picker in compose. Reorder them here, or with Shift+J and Shift+K in Accounts.

Config lives at ~/.config/tidemail/config.toml. TideMail puts its SQLite cache at ~/.local/share/tidemail/mail.db unless XDG_DATA_HOME points elsewhere. Each account's generated id is its permanent internal identity, so display names may be changed or shared safely. TideMail adds missing IDs automatically and writes a one-time .pre-account-ids.bak copy beside the config first. TideMail refuses to start on a malformed config and prints the exact path to repair, rather than loading defaults that could overwrite the real settings.

Build it

TideMail requires Go. Clone the repository, build, and run the binary:

git clone https://github.com/allisonhere/tidemail
cd tidemail
go build -o tidemail .
./tidemail

Run the test suite with:

go test ./...

Under the hood

Bubble Tea runs the application loop. Lipgloss handles terminal layout and color.

You can reuse two parts as standalone Go libraries:

• ripple, the compose editor
• tideui, the multi-pane TUI toolkit