Mail accounts

This page shows how to write a mail account in config.toml: one that reads from an IMAP server and one that reads a Maildir on disk. The complete list of keys is in config.toml: accounts.

What an account looks like

Each account is a [[accounts.mail]] table with two tables inside it. The store reads the mail and the transport sends it. Both are required, a Maildir account included.

[[accounts.mail]]
id = "work"
name = "Work"
address = "ada@example.org"
display_name = "Ada Lovelace"

[accounts.mail.store]
protocol = "imap"
username = "ada@example.org"
password = "#{pass show mail/work}"

[accounts.mail.store.settings]
host = "imap.example.org"
port = 993

[accounts.mail.transport]
protocol = "smtp"
username = "ada@example.org"
password = "#{pass show mail/work}"

[accounts.mail.transport.settings]
host = "smtp.example.org"
port = 587

id names the account for commands such as tcli send email --account work. Each id is used once among the mail accounts.
name is the label that tt shows. address is the address of the account. display_name is your name in the From line.
gpg_key is the OpenPGP key of the account. It is optional: see OpenPGP.
protocol says which plugin handles the part. username and password log in. A password without a username is an error.
settings holds the keys of the protocol. A number can be written as a number (port = 993).
Do not write a password in the file: see Passwords.

IMAP and SMTP

host is required. The other keys are optional.

Key	Meaning	Default
`host`	The server.	none
`port`	The TCP port, 1 to 65535.	IMAP 143, SMTP 587 (993 and 465 with `security = "tls"`)
`security`	`auto`, `none`, `starttls` or `tls`.	`auto`

auto picks the encryption from the port: TLS from the first byte on port 993 (IMAP) and 465 (SMTP), STARTTLS on any other port. It never falls back to clear text. A server that does not offer the encryption is refused, so the password never goes out in the clear. Only security = "none" allows that.

Maildir

A Maildir account reads the folders that another program keeps on disk, for example mbsync. Tilde does not download mail itself. It watches the new directories and shows mail that arrives from outside.

[[accounts.mail]]
id = "local"
name = "Local"
address = "ada@example.org"

[accounts.mail.store]
protocol = "maildir"

[accounts.mail.store.settings]
path = "~/Mail/home"
layout = "nested"

[accounts.mail.transport]
protocol = "smtp"
username = "ada@example.org"
password = "#{pass show mail/work}"

[accounts.mail.transport.settings]
host = "smtp.example.org"

path is required. A leading ~ is your home folder.
layout is nested (the default) or maildir++. In nested, every folder is a directory and a subfolder is a directory inside it (Archive/2024), as mbsync writes with SubFolders Verbatim. In maildir++, every folder is a directory of the root whose name starts with a dot and holds the path with dots (.Archive.2024), as Dovecot writes, and the root itself is the inbox.
The store needs no username or password. The transport is how the account sends mail.
With the mail cache on, a Maildir account gets an index of its messages for the search.

mbox

An mbox store reads a directory of mbox files, or one file, and only reads. It takes the same path key as a Maildir. The plugin is in the repository (plugins/Tilde.Plugin.Mail.Mbox), but tcli and tt do not load it yet: an account with protocol = "mbox" fails tcli check with No plugin handles the protocol 'mbox'.

Check the account

tcli check

This creates the store and the transport of every account and connects to nothing. Add --connect to log in to each server. The Reference lists all the keys of an account, and Chat accounts shows the other kind of account.