Tutorial: from nothing to a working tmail

This page takes you from an empty machine to one working account: install tmail, write config.toml, open the interface, read a message and send one. It takes about 20 minutes. Each step ends with a checkpoint that says what you should see. The reference pages hold the details; this page links to them.

1. Before you start

You need:

• a terminal of at least 60 columns by 15 rows;
• a mail account with IMAP and SMTP access: the user name, the password and the two host names;
• an app password, if your provider asks for one for programs other than its web mail (most large providers do when two-factor login is on);
• an editor in $VISUAL or $EDITOR: tmail has no editor of its own, and without these variables it runs vi;
• gpg, to sign, encrypt, or read signed and encrypted mail (see step 9).

This tutorial uses me@example.org, imap.example.org and smtp.example.org. Replace them with the values of your provider.

2. Install

On Debian and Ubuntu, use the apt repository (amd64 and arm64):

sudo curl https://codeberg.org/api/packages/squidd/debian/repository.key -o /etc/apt/keyrings/forgejo-squidd.asc
echo "deb [signed-by=/etc/apt/keyrings/forgejo-squidd.asc] https://codeberg.org/api/packages/squidd/debian stable main" | sudo tee /etc/apt/sources.list.d/tmail.list
sudo apt update && sudo apt install tmail

On other systems, download the archive of a release on Codeberg, unpack tmail-<version>-<rid>.tar.gz (.zip on Windows) and copy tmail to a folder on your PATH. The .deb files, the checksums, the nightly builds and building from source are in Install and build.

Check the install:

tmail --version

Checkpoint 1. One line with the version, the author and the project address:

~mail <version> - tom (tom@orivega.io) - https://codeberg.org/squidd/tildemail

<version> stands for the version you installed. tmail --help lists every command.

3. Write config.toml

tmail reads ~/.config/tildemail/config.toml. It creates the folder on its first run, but never the file. Create both now:

mkdir -p ~/.config/tildemail
$EDITOR ~/.config/tildemail/config.toml

Write one account:

[[account]]
name = "personal"
address = "me@example.org"
display_name = "Me Myself"
username = "me@example.org"
password = "${PERSONAL_MAIL_PASSWORD}"

[account.imap]
host = "imap.example.org"

[account.smtp]
host = "smtp.example.org"

• name is how tmail calls the account in commands and on screen.
• address is a bare address; the name goes in display_name.
• IMAP uses port 993 with TLS and SMTP uses port 587 with STARTTLS unless you set port and security. Check the values your provider gives and see config.toml for every key.

Never write the password itself in the file. ${PERSONAL_MAIL_PASSWORD} reads an environment variable. To read it from a password manager instead, write a command between #{ and }:

password = "#{pass show mail/personal}"

The command runs only when tmail connects, never when it loads the file. The rules are in Credentials.

Make the file private:

chmod 600 ~/.config/tildemail/config.toml

4. Check the file

Set the variable in the shell you start tmail from, then run tmail check. read -s asks for the password without showing it and keeps it out of the shell history:

printf 'Password: '; read -rs PERSONAL_MAIL_PASSWORD && export PERSONAL_MAIL_PASSWORD
tmail check

tmail check validates the file without connecting to any server.

Checkpoint 2. One line per account, and exit code 0:

personal  me@example.org  imap imap.example.org:993  smtp smtp.example.org:587  gpg key no

If you see something else instead:

Output	Fix
Configuration file not found: expected config.toml at '...'	The file is not where tmail looks. Check the path.
Account 'personal', key 'password': environment variable 'PERSONAL_MAIL_PASSWORD' is not defined.	Export the variable in this shell.
warning: '...' is accessible by group or others; run: chmod 600 '...'	Run the chmod it prints.
warning: unknown key '...' in account[1].smtp	A misspelled key, or a key written under the wrong [table].

Run tmail check again after every change to the file. See tmail check.

5. Open the interface

tmail

The first time, tmail opens the INBOX of the first account. Later it reopens the last folder you used.

Checkpoint 3. Two panes and a last line:

• on the left, the account with its folders; ● after the name means online, ○ offline;
• on the right, the messages of INBOX, newest first; ● marks an unread one;
• on the last line, where you are, the counts and the state of the account, then the keys that matter here:

personal ▸ INBOX │ 12 messages, 3 unread │ ● online       j/k move  Enter open  : command  ? help  q quit

If the account shows ! or ○, quit with q and go to When something goes wrong.

Move around

The keys follow vim:

Key	Does
j k	move down, up
gg G	first, last
Tab	the other pane
Enter	open the folder or the message
h	back to the folders (Esc too, in the reader)
?	the help: the keys and the commands
q	quit

Press g and wait: after a moment the which-key panel lists the keys that can follow (g Move the cursor to the first item). Esc cancels. See Which-key.

Press : to open the command line. Type fold and press Tab: it completes to folder. Esc closes the line. The commands are in The command line.

The full list of keys is in Key bindings.

6. Read a message

Move to a message in the list and press Enter.

Checkpoint 4. The reader takes the place of the list. It shows From:, Date:, Subject: and To:, a rule, and the text. The last line says message 1/12 (your position) and the keys of the reader:

personal ▸ INBOX │ message 1/12 │ ● online               n/p next/prev  A/S attachment  Esc back  ? help

• n and p move to the next and previous message.
• A selects an attachment and S saves it.
• Esc goes back to the list. The message is now marked read.

What the reader shows for HTML mail, attachments and signatures is in The reader.

7. Send a first message

Send the first message to yourself, so that nothing goes to anyone else by mistake.

In the list, press c. Your editor opens a file like this:

To:
Cc:
Subject:
Sign: no
Encrypt: no

Fill in the headers and write the text under the blank line:

To: me@example.org
Cc:
Subject: First message from tmail
Sign: no
Encrypt: no

It works.

Save and quit the editor.

Checkpoint 5. The last line asks:

Send to me@example.org? (y/N):

Type y and press Enter. Only y or yes sends; anything else cancels.

• If you quit the editor without changes, the last line says cancelled, nothing was sent.
• If you answer no, or the send fails, the text is not lost: a window says What you wrote is saved in: and gives the file.
• A copy of a sent message goes to the Sent folder of the account. Set sent_folder, trash_folder and archive_folder if your provider names them otherwise: a folder that does not exist is created, so dd would make a second Trash folder. The left pane shows the names the account uses.

r replies, R replies to all and f forwards the message under the cursor. A message goes out from the account of the open folder. See Writing.

Add a signature

Put the text in a file under ~/.config/tildemail/signatures/ and name it in the account, above [account.imap]:

[[account]]
name = "personal"
# ...
signature_file = "me.txt"

Written under [account.smtp], the key belongs to that table, and tmail check warns unknown key 'signature_file' in account[1].smtp. The signature is added under -- when the editor opens, so you can still change it. See Text signatures.

8. Day to day

• Search. / asks for a query on the last line: words that must all appear, from:name, subject:text. Enter searches the open folder; Esc in the list shows the folder again. See Search.
• Conversations. T groups the list by conversation and za opens or closes the one under the cursor. tmail remembers the choice. See Conversations.
• Act on a message. s flags it, U marks it read or unread, a archives it, dd moves it to the trash, m asks for a folder and moves it there. Delete and archive are moves, never a permanent delete. See Acting on messages.

Checkpoint 6. Press s on a message: ★ appears in its row. Press a: the last line says moved to Archive and the row leaves the list.

9. Next steps

Each of these is optional. Run tmail check after each change to config.toml.

A second account

Add another [[account]] block with its own name, [account.imap] and [account.smtp]. tmail check prints one line per account, and the interface lists both on the left. To write from the second account, open one of its folders first. Extra From: addresses of one account are identities: see Sender identities.

GPG

Signing and encryption use your own gpg, keyring and gpg-agent. Add the key to the account:

[account.gpg]
key = "0xABCD1234ABCD1234"   # your key id or fingerprint
sign = true
encrypt = "auto"             # encrypt when every recipient has a key

tmail check then says gpg key yes, and the compose file starts with Sign: yes. To import the key of a correspondent, run tmail gpg fetch bob@example.org (see tmail gpg fetch). The imported key is not trusted: check its fingerprint with its owner and certify it with gpg --sign-key, or a message to that person is not sent (Encrypt: no in the editor sends it in clear). The details are in GPG and Security notes.

A theme

The .deb installs eight ready-made themes. Write theme at the top of config.toml, before any table:

theme = "nord"

tmail themes list marks the active theme with *. :theme <name> in the interface tries one until you quit. From an archive, copy the themes/ folder to ~/.config/tildemail/themes/ first. See Ready-made themes.

A language

The interface speaks English. Write language at the top of config.toml, before any table, and restart tmail:

language = "it"

The .deb installs Italian, French, German and Spanish. From an archive, copy the langs/ folder to ~/.config/tildemail/langs/ first. See Choose a language.

A rule or a Lua script

Scripts live in ~/.config/tildemail/scripts/init.lua. A rule that archives a newsletter and marks it read:

rules.on("news", { from = "news@example.org" }, { mark_read = true, move = "Archive" })

Try it on the messages already in INBOX, without changing anything:

tmail rules run personal INBOX --dry-run

Rules run on new mail while the interface or tmail watch is open. See Rules and Scripting with Lua.

Shell completion

Save the completion script of your shell once, for example for bash:

mkdir -p ~/.local/share/bash-completion/completions
tmail completion bash > ~/.local/share/bash-completion/completions/tmail

zsh and fish are in Shell completion. Print the script again after an upgrade.

Manual pages

The .deb installs man tmail and man tmail-config. Without the package, read them with:

tmail man | man -l -
tmail man config | man -l -

See tmail man.

When something goes wrong

Run tmail check first. It reads the file without connecting and names the account and the key at fault. It stops at the first error, so run it again after each fix. It does not try the password or the servers.

Read the log. tmail writes one file per day in ~/.config/tildemail/logs/, named tmail-YYYYMMDD.log, and keeps the last 14. It names the accounts and the servers, never a password or the text of a message. For more detail, set the level for one command:

TMAIL_LOG_LEVEL=debug tmail

At debug the log says which servers tmail connects to and how the certificate is checked. The interface writes these lines to the file only; a command such as tmail send also prints them on standard error. log_level = "debug" at the top of config.toml does the same for every run. See Logging.

Common causes:

• A login refused: the provider may want an app password, or IMAP turned on in its settings.
• A #{command} that fails is reported only as the credential command failed with exit code N. Run the command by hand in the same shell; a locked password manager is the usual cause.
• A server with a self-signed certificate needs certificate in [account.imap] or [account.smtp]. See Validation.
• The interface says it is in reading mode: another tmail (or tmail watch) already runs the scripts. See One tmail at a time.

The cache. tmail keeps a copy of each IMAP account in ~/.config/tildemail/cache/, one SQLite database per account. When the server cannot be reached, the account shows ○ and you read what the cache holds. tmail cache status shows what it holds, and tmail cache clear empties it; the cache is only a copy and fills again as you read. See Mail cache.

Other files. ~/.config/tildemail/state/ui.toml keeps the last folder and the history of the : line; delete it to start the interface fresh. Every file and folder is listed in Files and folders.