The terminal interface

tmail without arguments opens the terminal interface. It shows the folders of every account, the messages of a folder and one message at a time, acts on messages (read, flag, delete, archive, move), searches the open folder and writes mail through your editor. What is not there yet lists what is still missing.

The interface needs a terminal. When the input or the output is redirected, tmail prints its help instead (see tmail).

The screen

╭┤Folders├───────────────────╮╭┤work ▸ INBOX├──────────────────────────────────────────╮
│▾work ●                   4 ││▌●   "Ann Rossi" <… Welcome to tmail              17:38 │
│  INBOX                  3  ││ ●   "Marco Bianch… Re: Contratto fornitore       13:38 │
│  Sent                   1  ││     "Codeberg" <n… Weekly digest                 27 Oct│
│▸home ●                   1 ││                                                        │
╰────────────────────────────╯╰────────────────────────────────────────────────────────╯
work ▸ INBOX │ 4 messages, 3 unread │ ● online       j/k move  Enter open  : command  ? help

The top bar (not in the picture): a row above the panes that your scripts fill with bar.top (see bar), in the top_bar_fg and top_bar_bg colors of the theme or in the color the script gives it. It is hidden while the script gives it nothing to show, and then the panes start at the first row. tmail draws nothing there by itself.
Left, as wide as its names: the accounts and their folders. The pane takes the width of its longest row, at least 16 columns and at most 40% of the screen, and follows the unread counts and the folded accounts as they change. ▾ is an account that shows its folders, ▸ one that is folded. The number at the right of a row is the number of unread messages. INBOX comes first; the other folders follow by name. Folders are a tree under their account, see Folders as a tree.
Right, the rest: the messages of the open folder, newest first. When you open a message, the reader takes this place.
The last line: where you are, the counts, what else there is to tell (the position and the signature in the reader, a search, work in progress), the state of the account, and on the right the keys that matter in the pane you are in. It is not a filled band: the line sits on the background of the theme, the place is in bold, the separators are dim (the border color), the connection has its mark in the color of its state (green for online, ! in red for an error) and each key is in bold with its meaning in the muted color; the picture cannot show that. A message appears here for a few seconds when something happens, in place of the left side. A script can build this line itself with bar.bottom (see bar); what you see here is the script that ships with tmail, which tmail bar dump prints. When the line is wider than the screen, the keys at the right drop out first, from the last one, and then the left side is cut. In reading mode, and before the script has answered, the line is a plain version of the same texts without styles.

At the end of a row of the sidebar, ● after an account name means online and ○ means offline (the last connection failed; the cache is shown). ! means the account reports an error. Only IMAP accounts with the cache on report that they are offline; every other account is shown online.

The number next to a folder is the number of messages loaded, not a count from the server. A + after it means more may exist than the loaded rows.

The layout is tested from 60 columns by 15 rows up to 200 by 50. Long texts are cut to the width of their pane, and a change of size while the interface runs redraws the screen.

The message list

Each row has, from the left:

Part	Meaning
`▌`	the row you are on
`✓`	a marked message (see Marking several messages)
`●`	unread
`★` or `↩`	flagged, or answered
`s` or `#`	signed, or encrypted (a theme can draw a padlock, see Themes)
sender	the name of the sender, or the address when there is no name
subject	the subject, cut to the width of the pane
date	the time for today, `dd MMM` for this year, `yyyy-MM-dd` for older mail

Conversations

T (or :messages.view_toggle) turns the list into a conversation view; :messages.view_threads turns it on and :messages.view_list back to single messages. It is off until you turn it on, and tmail remembers the choice.

With it on, a conversation of two or more messages is one row: its newest message, with ▸ (3) before the subject (three messages) and the row in bold when the conversation holds an unread message. za (messages.thread_toggle) opens the conversation under the row, which shows its other messages below it, newest first, each marked ↳, and the arrow becomes ▾; za again closes it. Opening a row (Enter) reads that message. A message alone in its conversation is a plain row. The rows of a conversation have their own background, the conversation_bg color of the theme.

Messages are grouped by the Message-ID, In-Reply-To and References headers they carry, so two replies to a message that is not in the folder still belong together. A reply that has no thread header at all is joined by its subject, without Re:, Fwd: and the like, to the message with that subject that came just before it, if that was in the last 60 days. Two messages that are both called Hello, and a reply that has headers, are never joined by their subject, so a forwarded newsletter does not pull every issue into one conversation. Only the last 50 ids of a References header are followed. Only the messages of the open folder are grouped; a reply you sent from another folder is not in the conversation. A search always shows single messages.

The message you read stays where it is: while a message is open in the reader, its conversation is drawn open, and za asks you to go back to the list first. n and p step through the rows that are shown, so open a conversation to step through all its messages. The status line counts the messages that are loaded, not the rows.

The row you are on is drawn with the selection colors when the list has the focus, and with the border color as background when it does not, so the selection is never invisible.

Control characters in a sender, a subject or a body are shown as spaces. A message cannot move the cursor, clear the screen or change the title of your terminal.

Panes and focus

Folders as a tree

A folder such as Lists/rust is drawn under Lists, indented, with only its own name:

▾ work                    ▾ work
  INBOX         3           INBOX           3
  Lists/rust    1           ▾ Lists
  Lists/go      0               go          0
  Archive       0               rust        1
                            Archive         0

The levels of a name are separated by the character the server uses (/ or . for IMAP); a Maildir uses /, and . for the Maildir++ layout. A folder with no separator in its name is at the top, as is a folder whose name has an empty part (a//b).
A parent that the server has no folder for is drawn too, as a container: it opens and closes, but it has no messages to open.
A folder with folders under it has an arrow, like an account. za in the sidebar (folder.toggle) opens or closes the branch under the cursor (or the account, when the cursor is on one). Enter and l do the same on a container, and keep opening the messages on a folder that exists.
A closed branch shows the unread count of everything under it; an open one shows its own. The count of an account is the sum of its folders.
Closing the branch of the folder under the cursor moves the cursor to the branch. Opening a folder by name (the last folder at the start) opens the branches above it.
The open branches are remembered in state/ui.toml, like the open accounts. A branch that is not there any more is not saved again.
Two rare cases are not exact: an account whose name has a colon in it can swap branches with another account at the next start, and a cache written by an older version shows a Maildir++ account as a flat list until its folders are read from the disk.

There are three places for the focus: the sidebar, the list and the reader. Tab and Shift-Tab move between the sidebar and the list; Enter or l on a folder opens it and moves the focus to the list; Enter, o or l on a message opens it in the reader; h in the list goes back to the sidebar. Esc or h in the reader goes back to the list.

<leader>e (Space, then e, in the sidebar and in the list; also :sidebar.toggle) hides the sidebar, so that the list and the reader use the whole width, and shows it again. Hiding it moves the focus to the main pane (the list, or the reader when it is open); showing it gives it the focus, so you can pick a folder at once. While it is hidden, Tab, Shift-Tab and h do not go to it (in the reader Tab then does nothing; Shift-Tab, h and Esc still go back to the list). The reader does not bind <leader>e, because Space there is “page down” and a binding that starts with it would make it wait for a second key: run :sidebar.toggle there, or bind it yourself with keys.bind. tmail remembers the choice in state/ui.toml: a sidebar that you hid stays hidden at the next start.

Closing the reader leaves the list where you were. When new mail arrives and you have not moved the cursor, the list follows the newest message; once you move, it stays where you put it.

Keys

The complete default keybindings reference lists every key, its context and its effect. The interface reads these bindings: the vim preset by default, with the changes init.lua makes. The keys that matter for reading are:

Key	Does
`j` `k`, `gg`, `G`	move, first, last
`Ctrl-d` `Ctrl-u`, `Ctrl-f` `Ctrl-b`	half page, page
`Enter`, `l`, `o`	open the folder or the message
`h`, `Esc`	go back
`Tab`, `Shift-Tab`	next, previous pane
`T`, `za`	conversations on or off, open or close a conversation, in the list
`n`, `p`	next, previous message, in the reader
`A`, `S`	next attachment, save it, in the reader
`:`	open the command line
`?`	show the help
`q`	quit

The mouse is not used: the interface is driven by the keyboard.

The interface owns the keys while it runs: Esc never quits and Ctrl-Z never suspends it. A key with a count or a sequence (5j, gg) works as the key layer describes in Counts and Waiting for the next key: a pending sequence is resolved after timeout_ms.

? shows every binding of the context you are in and every command, in a window that scrolls with j and k and closes with Esc or q.

Which-key

When a key sequence stays pending for 400 ms (the first g of gg, <Space> before a binding of yours, any prefix of a binding), a panel above the last line lists the keys that can follow and what each one does:

╭┤<Space>├───────────────────────────────────────────────────────────────╮
│a  archive and mark read  n  move to Newsletters                         │
╰─────────────────────────────────────────────────────────────────────────╯

The keys are those of the context you are in plus global; on the same keys the context wins. A count in front (5g) is ignored.
An action shows its own description. A Lua binding shows the description you gave it, keys.bind(lhs, fn, "text") (see Binding from Lua), or Lua function.
A key that only starts longer bindings says how many (+3 bindings); a key that ends one binding and starts longer ones shows its action and +N.
The panel takes at most 8 lines, in as many columns as fit; what does not fit ends with +N more.
While the panel is shown the sequence does not time out: it waits for the next key, so you can read it. Esc cancels the sequence. The panel also closes when the focus moves to another pane or the command line opens. It only draws: the keys still go where they would have gone.
A description is cut to 80 characters. A sequence with no continuations to list (a count, for example) shows no panel and times out after timeout_ms as before.

The command line

: replaces the last line with a command line. It takes:

the built-in commands: quit (or q; it asks Quit tmail? (y/N): first), quit! (or q!; it quits without asking), help, folder <account>/<folder>, theme <name>, about, message.log, jobs, cache.download [account], cache.stats and plugins.show (see Messages, jobs and the cache and Plugins);
the names of the input actions, such as message.next;
the commands your scripts define with commands.add (see Scripting).

Key	Does
`Enter`	run the line
`Esc`	cancel and go back to the last line
`Tab`	complete the command name, or the argument of `folder`, `theme`, `help` and `cache.download`; press it again for the next match
`Up`, `Down`	walk through the history

The history keeps the last 200 distinct lines and is saved between runs. A command that answers with one line shows it on the last line; one that answers with several lines shows them in a window like the help. A Lua error in a command or in a key appears as an error message and in the log; it never stops the interface.

:theme <name> changes the theme until you quit. The theme you start with is the theme key of config.toml.

The reader

The reader shows the header (From, Date, Subject, To, Cc when there is one), a rule, and the text of the message wrapped to the width of the pane. Quoted lines (those that start with >) are drawn in the quote color. Opening a message marks it read.

A message that has only an HTML part is drawn with its formatting: headings in the accent color and bold, bullet and numbered lists, quotes with a bar in the margin, code in a muted color, tables in aligned columns, and bold, italic and underlined text. A link to a web site shows its text underlined and, unless the text is exactly that site, the host it really goes to in brackets, such as Read more (news.example.org); a text that only contains another host, such as www.paypal.com/login, still shows the real one. A link to an address (mailto:) shows the whole address, query included. A link that goes nowhere that can be named, such as a relative link, is plain text. The address behind a link is the first thing to check in a suspicious mail. An image shows its description in square brackets, and nothing when it has none. Nothing is downloaded, no link is opened, and the colors and layout of the HTML are ignored. A message with a plain part is shown as that part.

Attachments: when the message has some, they are listed under the header with name, type and size. A selects the next one; S opens a prompt on the last line (save to:) with the folder of the last save, or your home folder; Enter saves the file there and says saved <name>. A file that already exists is never overwritten.
Security lines: an encrypted or signed message shows up to three lines under the headers, each with one idea:
```
Security:   Encrypted · decrypted with your key
Signature:  Good · signed by Ann Rossi <ann@x.org>, matches From
Key:        27A0 FBEE 8B42 857F B8D2 CD54 9FFF 0D1F 4AA1 9655
            verified: you can rely on it (validity full, owner trust unknown)
```
- Security: appears only for an encrypted message: decrypted with your key, or NOT decrypted, in which case a Problem: line gives the reason.
- Signature: appears only for a signed message. Good is a valid signature of a key that matches the From address (the name after signed by is the one the key carries; for Untrusted it is only what the key says about itself, and for BAD it is left out); Unknown key means the key is not in your keyring, so it cannot be checked (K, signature.fetch_key, looks it up: see Looking up the key of a signature); Untrusted is valid but the key is not trusted for the From address; BAD means the check failed and the line says not to trust the message.
- Key: gives the fingerprint of the signing key in groups of four, so you can compare it by eye, and, for a key that is in your keyring, whether you can rely on it: verified (validity full or ultimate), valid, but not for the From address (a valid key under an Untrusted signature: the validity is about the whole key, not about this address), partly verified, not verified yet: check the fingerprint with its owner, or do not rely on this key (revoked, expired, invalid, disabled or never trusted). The words in brackets are what gpg reports: validity is how far gpg believes the key belongs to its user ids; owner trust is how far you trust its owner to certify other keys.
- A message that is neither encrypted nor signed shows none of these lines. A long line wraps under its label.
Encrypted mail is decrypted when you open it. gpg is first run so that it cannot ask for a passphrase: when the agent already holds it, the message simply opens. Otherwise the interface leaves the screen to your terminal for the pinentry and comes back. Encrypted mail from Proton Mail, which arrives as a multipart/mixed with attachment.gpg and encrypted.asc as attachments, is opened the same way: you see the text and the attachments of the inner message and the signature, and the public key that Proton attaches is listed as an attachment you can save (it comes from outside the encryption: check its fingerprint before you trust it). A message that cannot be decrypted shows Security: ... NOT decrypted, a Problem: line with the reason and an empty body.

n and p move to the next and the previous message of the list without going back to it. The status line says which message you are on, for example message 2/3.

New mail and polling

A folder of the watch list of an account is followed by the watcher (a Maildir is checked every 5 seconds): a new message appears in the list without a key, and the sidebar counts change.
A folder that is open but is not in the watch list is read again every 60 seconds for new messages, and every fifth time also for changed flags and vanished messages. A folder of the watch list gets its new messages from the watcher; the changes made elsewhere (read or deleted on another device) are looked at every fifth minute. In reading mode no watcher runs, so every folder is read this way.
The counts of the folders are read again every 5 minutes.
The new_mail handlers, the rules and the jobs of your scripts run while the interface is open, as they do with tmail watch.

One tmail at a time

The hooks, the rules and the jobs must run in one process only, so the interface takes the same lock as tmail watch. If another tmail holds it, the interface opens in reading mode: it shows and reads mail, and says on the last line that the hooks, rules and jobs run in another tmail. In that window no Lua engine runs, so your Lua commands and key bindings are not there.

State

The interface remembers the last folder you used, which accounts and which branches of folders are open, whether the list shows conversations, whether the sidebar is shown and the history of the command line, in ~/.config/tildemail/state/ui.toml, a TOML file like the rest of the configuration. Delete the file to start fresh. A ui.json left by an older version is not read: the interface starts fresh once and the old file stays where it is, so you can delete it.

Closing

q, :quit! (:q!), SIGTERM and SIGHUP close the screen in order: the services stop, the state is saved, the terminal is given back and the lock is released. :quit (:q) does the same after asking Quit tmail? (y/N): on the last line: only y or yes quits; Enter on an empty line, any other answer and Esc leave tmail running. The q key does not ask. The exit code is 0. If the terminal disappears (a dropped connection, a closed window) and the screen does not close within five seconds, the process ends and the system releases the lock.

Acting on messages

These work on the message the cursor is on, in the list and in the reader (the keys are those of the vim preset; the action names work as : commands too):

Key	Action	Does
`U`	`message.toggle_seen`	marks the message read, or unread when it is read
`s`	`message.toggle_flag`	flags the message, or removes the flag
`dd`	`message.delete`	moves the message to the `trash_folder` of its account
`a`	`message.archive`	moves the message to the `archive_folder` of its account
`m`	`message.move`	asks `move to:` on the last line and moves the message to the folder you type
`V`	`message.show_source`	opens a window with the raw message, as the server holds it
`u`	`message.undo`	puts back the messages that the last delete, archive or move took out of a folder

Each action asks the server first. The row and the unread counts change only when the server did it; if it failed, the row stays and the reason is on the last line.
Delete and archive are moves, never a permanent delete: to get a message back, move it out of the trash. The trash or archive folder is created when it does not exist yet (a new local Maildir). A message that is already in that folder says so.
m takes the name of a folder of the account as the server lists it; any other name is refused and nothing moves.
V shows the headers and the body exactly as they arrived, so an encrypted message appears as its PGP/MIME ciphertext, not decrypted. The text is cleaned like every text from a message: the escape byte and invisible bidi controls are dropped and other control characters become spaces, so nothing in the message can move the cursor or redraw the screen. A message over 256 KiB is cut and the last line says how much is shown. The message is not marked read.
In the reader, after a message is moved away the next one opens; when none is left, the list is shown.

Undoing a move

u puts back the messages that the last dd, a or m moved, in the folder they came from: one message, or all the marked ones of a group. Press it again to go one move further back. The last line says 1 message moved back to INBOX.

Only moves can be undone. Flags (U, s) are toggles: press the key again.
The history is in memory, 20 moves long, and is gone when tmail closes. A move that failed is not in it; a group that stopped half way can undo the messages that went through.
The message is found again in the folder it was moved to by the UID the server gave it (IMAP servers with UIDPLUS, and Maildir folders, say it). Without it, tmail looks for the Message-ID in the first 500 messages of that folder. A message that is not found, because it was moved on or deleted for good, is reported (1 message could not be found in Trash) and dropped from the history.
If putting a message back fails, the last line says how far it got and the ones that are left stay in the history for another u.
Undo works in the list and in the reader; it is not undone itself (there is no redo). The scripts see the moves back as message_moved events like any other move.

Marking several messages

In the list, x marks the message the cursor is on, and marks it no more when it is marked already. A marked message has a ✓ in front of its state. The cursor does not move.

Key	Action	Does
`x`	`message.toggle_select`	marks the message, or unmarks it when it is marked
	`message.select`	marks the message; it can be called for as many messages as you like
`<C-a>`	`message.select_all`	marks every row of the list
	`message.select_clear`	unmarks every message
	`message.set_read_selection`	marks the marked messages read and unmarks them; says `no messages are marked` when there are none

U, s, dd, a and m act on the marked messages when there are any, and on the message under the cursor when there are none. m asks the folder once for all of them. U marks them all read when any is unread and all unread when every one is read; s flags them all when any is not flagged and removes the flag when all are flagged.
The messages go one after the other. The first failure stops it: the last line says stopped after 3 of 10: <reason>, the ones that went through are unmarked, and the others stay marked so the action can be repeated.
When it is done the messages are unmarked. Esc in the list unmarks them too (a second Esc leaves a search).
To mark every message of a folder read, run message.select_all and then message.set_read_selection (:message.select_all, :message.set_read_selection, or keys of your own).
With conversations on, a row is a conversation: x marks the message the row stands for, <C-a> marks one message for each row, and the actions work on those messages, as dd does on a single row.
The marks belong to the list on screen: opening another folder, showing the results of a search and leaving them forget the marks, and a message that is moved or deleted elsewhere drops out of them. In the reader, dd, a, m, U and s work on the open message only, whatever is marked.

Search

/ asks for a query on the last line. The query is the one the library already understands: words that must all appear in the subject or the sender, from:name and subject:text. Enter searches the open folder and shows the matches in the list, and the last line says search: <query> (N found). While the search waits for the server the last line says searching for <query> and the search is a job (see :jobs). While the results are shown the folder is not refreshed and new mail is not added. Esc in the list leaves the search and shows the folder again, and so does opening another folder. Searching every folder of an account is not there yet.

Writing

Key	Action	Writes
`c`	`message.compose`	a new message, from the account of the open folder; it asks for the `To:` first
`r`	`message.reply`	a reply to the sender of the selected message
`R`	`message.reply_all`	a reply to the sender and the other recipients
`f`	`message.forward`	the selected message, forwarded

The message opens in $VISUAL or $EDITOR: the interface leaves the screen to the editor and comes back when you quit it. The first lines are the headers (To:, Cc:, Subject:, Sign:, Encrypt:), then a blank line and the text. A reply or a forward is read in full from the server, not taken from the list.
A new message starts with To: on the last line, before the editor opens. Tab completes the address after the last comma from the address book (the most frequent first; Tab again for the next one), and Enter opens the editor with the To: filled. Enter on an empty line opens it with no recipient, as the headers can still be edited there; Esc cancels the message. Text that is not a list of addresses is refused: the prompt says To (not an address, try again): and keeps what was typed. A reply, a reply to all and a forward do not ask: their recipients come from the message.
Quitting the editor without changes, or with no recipient and no text, cancels the message: cancelled, nothing was sent.
Before anything is sent, the last line asks Send to a@x, b@y? (y/N): . It names the recipients and says [signed], [encrypted] or both; when a message that should be encrypted cannot be (a recipient has no public key), it says why in front of the question. When the recipients or the note do not fit on the line, a window lists them all first and the question says Send to 6 recipients (see window)?. Only y or yes sends; Enter on an empty line, any other answer and Esc do not.
If gpg needs your passphrase for signing or encrypting, the pinentry has the terminal as it does when you read an encrypted message.
A message is sent from the account of the folder that is open; to write from another account, open one of its folders first. A copy goes to the sent_folder of the account.
The text you wrote is never thrown away. If the send fails after you wrote it (the server refuses, gpg fails, the network is down), or you answer no at the question, the text is saved in a file of its own, readable by you only, and a window says where. The folder is $XDG_RUNTIME_DIR/tmail-unsent when that exists (memory, cleared when you log out, so the decrypted text of a reply to an encrypted message does not stay on a disk) and ~/.config/tildemail/state/unsent otherwise. A later failure never replaces an earlier file.
Only one message can be written at a time.

Messages, jobs and the cache

:message.log opens a window with every message that the last line showed since tmail started, the newest first, with the date, the time and how serious it was (info, ok, warning, error). It keeps the last 500. The start and the end of a search and of a cache download are there too.
:jobs opens a window with every job of the scheduler that the library and the interface share (see Background jobs): how long each has run (waiting while it needs a worker), what it does and how far it is, and for a recurring job of a script its interval, next run, number of runs and last error. A search and the cache download are jobs that the interface runs itself: they start at once and take no worker of [jobs] workers, so a long download never holds back the jobs of your scripts. While a job runs, waits for a worker or a recurring job is at work, the middle of the last line says so (searching for invoice, or 2 jobs when there are several).
:cache.stats opens a window with what the cache of each account holds, the figures of tmail cache status (without its list of orphan databases): the number of headers, the number and size of the stored messages and how much of max_size_mb they use, and the size of the database file. An account that reads a Maildir says so, and a cache that is off says so. It only reads: it never creates a cache.
:about opens a window with the version, the author, the address of the project, the license and a line that says ~tilde is a sponsor of FLUG Firenze, then the notices of the third-party packages.
:cache.download [account] downloads every message of every folder of the account (of every IMAP account when none is named) into the cache, newest first, so that you can read and search them offline. It runs in the background as a job: you can go on reading, and the last line shows the folder and the number of messages. A message that is already in the cache is not downloaded again; the last line counts those apart (N downloaded, M already in the cache). The accounts are downloaded at the same time. Within an account the messages are read in batches of up to 20 messages and 8 MB, by the sizes the server reports when it lists them (a bigger message is read alone), with two fetches (the flags, then the messages), over up to 3 connections of their own beside the one the interface uses, opened together so that the credentials are resolved once for them; when the server refuses one more connection, the download goes on with the ones it has, and with none it uses the connection of the interface. A batch that fails is read again one message at a time. For each account the download stops a little before what it read reaches max_size_mb of the cache, which is the limit of one account (past it, the cache would drop the messages read first to make room for the newest). The size of a message is known only once it is read, so the first message of an account is read alone; after it, each connection holds room for its batch as if every message were as big as the biggest read so far, and the connections share what is left. So an account passes the limit by no more than its first message, unless a later message is bigger than every one read before it. A connection on which five messages in a row fail stops reading and leaves its messages to the others; when no connection is left, the download gives up on the account. Either way the other accounts go on, and so does the download when something unexpected breaks one account: the last line names it. A folder that cannot be listed is skipped. The whole download stops when you quit, and its connections are closed. The last line and the log say what was left out. Only one download runs at a time. A Maildir account has no cache and is skipped; with the cache off in the configuration the command says so.

What is not there yet

Searching every folder of an account, drafts, attachments to a message you write, and a folder list that follows the hierarchy of the server. The interface is in English unless you choose another language (see Languages).