Lumail - The console email client


Getting Started

This page briefly describes how you would get started using lumail.

It only covers the bare essentials and documents the behaviour of the client with the default settings. (You can configure the client significantly using the available lua primitives.)

Before proceeding you'll need to install the client.

Configuration Files

lumail is configured by a pair of Lua configuration files, which are loaded at startup-time:

If present the following configuration files are read and executed:

You may specify an additional file via the --rcfile command-line argument:

~$ lumail --rcfile ~/conf/lumail.lua

Note: The default configuration file uses the load_directory() function to execute all files matching the pattern ~/.lumail.d/*.lua. This is optional behaviour which you can remove or modify.

Initial Configuration

The initial configuration will consist of you telling lumail where to find your mail, setting your from address, and configuring the sending of new mail.

The sample configuration file contains settings that you can adopt or adapt.

Once you have these settings defined you'll be able to use the client, and consider looking at the example functions we've documented for further inspiration.

Basic Usage

lumail is a modal mail client, which means you're always in one of three modes (see global_mode() for documentation):

  • maildir-mode
    • This mode allows you to view a list of Maildir folders.
  • index-mode
    • This mode allows you to view lists of messages.
  • message-mode
    • This mode allows you to view a single message.

If you launch lumail you'll start in "maildir" mode, which consists of a scrollable list of folder-names. You can page up/down with `j/k`, or search with `/`.

Note: The keybindings listed here are the defaults.

Each folder-name has a small [ ] next to it. This indicates whether the folder is selected or not. Unlike other mail-clients you can open multiple folders with lumail, by selecting several folders and then opening the result, which will show you the messages in all the selected folders.

To open the single folder which is highlighted, press RETURN. Otherwise you may toggle the folders selected state with "SPACE". Once you've selected as many folders as you wish you can press "I" to view the index-mode.

index-mode is navigated the same way as maildir-mode; use `j + k + /` to move around, then press "SPACE"/"RETURN" to view an individual message.

That's the rough introduction to using the client.

Advanced Usage

Because lumail has a built-in Lua interpreter you can configure it to do many interesting things. The supplied lumail.lua file shows examples of limiting the display, or opening several folders via a single-keystroke.

As well as the sample configuration file there are sample functions available to give you inspiration.

At any time you can evaluation/call Lua functions via the prompt, you're not limited to binding them to keys. In any mode pressing ":" will prompt for input, and evaluate it. For example you might press ":" then enter:

msg( "Lua rocks!" );

This uses just one of the lua primitives available to you, (msg outputs a message to the status area).

Combining primitives works exactly as you'd expect:

msg( "You are called : " .. prompt( "Enter your name:" ) );

(This prompts for your name, then displays it. In Lua ".." is used for string concatenation.)