termmail guide: setup, keys, attachments and troubleshooting

Q: termmail says lynx is missing. What do I install?

Install lynx with your package manager: sudo apt install lynx on Debian or Ubuntu, sudo dnf install lynx on Fedora, sudo pacman -S lynx on Arch, or brew install lynx on macOS. Without lynx, termmail strips HTML tags crudely.

Q: Where is the configuration file?

In ~/.config/termmail/config.json. The directory is created with mode 700 and the file with mode 600. It contains your accounts, the active account index and the server settings.

Everything after installation: how the first-run wizard works, what each key does, where settings live, how to send and save attachments, and what to check when a login or a message fails.

Starting termmail

termmail
termmail --version
termmail --help

With no argument it opens the active account, or the setup dialog on first run. There is no account to create and no daemon to start; the program connects, lists the current folder and exits when you press q.

First run: the setup dialog

Enter your e-mail address, then the IMAP and SMTP server, port, username and password. termmail tries to fill those in for you, in this order:

Presets for Gmail, Outlook, Yahoo, iCloud, Fastmail, GMX, Zoho and Yandex.
SRV records for _imaps._tcp and _submissions._tcp.
Autoconfig at autoconfig.<domain> and /.well-known/autoconfig/mail/config-v1.1.xml.
MX records when they point at a provider with a known preset.
A host guess such as mail.<domain>.

The dialog title shows which method produced the values, for example preset or SRV. You can edit every field before saving. Settings are written to ~/.config/termmail/config.json with mode 600.

Use an app password when your provider offers them. Gmail, Outlook and Yahoo reject your normal account password for IMAP even when the password itself is correct.

Gmail

Enable two-step verification on your Google account.
Create an app password at myaccount.google.com/apppasswords.
Enable IMAP in Gmail’s settings.
Use imap.gmail.com on port 993 with SSL and smtp.gmail.com on port 587 with STARTTLS.

Proton Mail

Proton does not expose IMAP directly. Run Proton Bridge, then use the local IMAP and SMTP host and port the bridge shows, usually 127.0.0.1 with the bridge password rather than your Proton password.

Multiple accounts

Each entry in the accounts array has its own email, user, password, IMAP and SMTP settings. Press A or use the Account toolbar button to switch. active records which one opens first. termmail opens one mailbox per account at a time; switching does not keep a second connection open.

Keyboard shortcuts

Key	Action
`Tab`	Move focus: folders → messages → toolbar
`↑` `↓`	Select a folder or a message
`Enter`	Open a message or press the focused button
`c`	Compose a new message
`r`	Reply to the selected message
`f`	Forward the selected message
`d`	Delete the selected message
`a`	List attachments and save one to disk
`A`	Switch account
`/`	Search the current mailbox
`R`	Refresh the folder
`?`	Help
`q`	Quit

The compose window

Tab moves between To, Subject, the body and the three buttons. Typing in a focused address field replaces its contents; Ctrl-A selects all. F2 or the Send button sends; Esc or Cancel abandons the message. Attach asks for a path and adds the file with a MIME type guessed from its extension.

If your SMTP server presents a certificate that does not match on port 587, termmail falls back to implicit TLS on port 465 automatically. That fallback is reported in the status line, not hidden.

Attachments

Open a message and press a. termmail lists every attachment with its name and human-readable size. Choose one and confirm the destination; the default directory is ~/Downloads. Names are sanitised so a path in a filename cannot escape the chosen directory. Attachments cannot be opened from inside termmail; save them and open them with the program you normally use.

Deleting and searching

d marks the message deleted and expunges the folder. There is no undo. / runs an IMAP TEXT search in the current folder and replaces the message list with the result; refresh or reopen the folder to clear it.

Configuration file

The file is ~/.config/termmail/config.json. The directory is created with mode 700 and the file with mode 600 because it contains your passwords.

{
 "accounts": [
  {
   "email": "you@example.com",
   "user": "you@example.com",
   "password": "app-password",
   "imap_host": "imap.example.com",
   "imap_port": 993,
   "ssl": true,
   "smtp_host": "smtp.example.com",
   "smtp_port": 587,
   "starttls": true,
   "smtp_ssl": false
  }
 ],
 "active": 0
}

There is no keyring integration. Treat the file like an SSH key: keep it readable only by you, and do not put it in a synced folder you do not control.

Troubleshooting

termmail says lynx is missing. What do I install?

Install lynx with your package manager: sudo apt install lynx on Debian or Ubuntu, sudo dnf install lynx on Fedora, sudo pacman -S lynx on Arch, or brew install lynx on macOS. Without lynx, HTML tags are stripped crudely and the text is harder to read.

Why does the login fail even though the password is correct?

Most providers reject your normal password for IMAP. Create an app password, make sure IMAP is enabled, and check the port and encryption: 993 with SSL for IMAP, 587 with STARTTLS or 465 with implicit TLS for SMTP.

Where is the configuration file?

In ~/.config/termmail/config.json. The directory is created with mode 700 and the file with mode 600. It contains your accounts, the active account index and the server settings.

Can I use Proton Mail?

Yes, through Proton Bridge. Run the bridge locally and use the IMAP and SMTP host and port it shows, usually 127.0.0.1 with the bridge password rather than your Proton password.

If the interface looks garbled, make sure TERM is set to a real terminal type such as xterm-256color. If a message appears empty, it may be an HTML-only message and lynx may be missing. If the program exits immediately, run it from a terminal so the error is visible; IMAP and SMTP failures are reported in the status line.