Skip to content
A console-based mail-client with integrated Lua scripting support.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create FUNDING.yml Jun 26, 2019
lib only store headers for existing messages on disk Dec 14, 2017
sample.lua add oneshot compose script Feb 24, 2019
src initialize m_running in screen.h Feb 24, 2019
t Use a valid (transparent!) PNG image in our test. Oct 29, 2017
.gitignore No need to ignore the test-suite file any more Jan 9, 2017
.travis.yml Directory completion adds "/" to directories. Oct 29, 2017 Minor documentation updates. Jun 19, 2017
Doxyfile Exclude the jsoncpp files from the docs. Jan 19, 2016 Minor documentation updates. Jun 19, 2017 rename lumail2.lua to global.config.lua in and the … Jul 4, 2017 Moved the IMAP dependency documentation into Jun 25, 2017
Makefile Minor spelling fixes; via ispell Jul 9, 2017 Fixed typo in hyperlink Jun 29, 2016
global.config.lua Merge pull request #357 from fischerling/allow_oneshots_with_tui Feb 24, 2019
user.config.lua Fixed typo in path Jul 12, 2017

Build Status license


lumail is a modern console-based email-client, with fully integrated scripting, implemented in the Lua programming language.

Although primarily developed and tested against GNU/Linux it should run upon Mac OS X, and FreeBSD. If your system isn't supported, and is Unix-like then this is a bug which should be fixed.

lumail is primarily designed to operate against local Maildir-hierarchies, but IMAP support is available, as well as support for GPG for security.

This file contains brief details of the project, with more complete documentation provided on the homepage. The following links on the project website should be a good starting point:


Lumail is a console-based mail client, which is modal. A modal client means that you're always in one of a small number of states, or modes:

  • maildir-mode
    • Allows you to see a list of message-folders.
  • index-mode
    • Allows you to view a list of messages.
      • i.e. The contents of a folder.
  • message-mode
    • Allows you to view a single message.
      • attachment-mode is related, allowing you to view the attachments associated with a particular message.
  • lua-mode.
    • This mode displays diagnostics and other internal details.
  • keybinding-mode.
    • Shows you the keybindings which are in-use.
    • Press H to enter this mode, and q to return from it.

Compilation & Installation

Running make install will install the binary, the libraries that we bundle, and the perl-utilities which are required for IMAP-operation.

If you wish to install manually then please copy:

  • The contents of lib/ to /usr/lib/lumail.
  • The contents of perl.d to /usr/share/lumail/.

You can also see the notes below about running directly from a git-checkout of our repository. Note that if you wish to use IMAP you'll need to install the extra dependencies for that.


Once installed you'll want to create your own personal configuration file.

To allow smooth upgrades it is recommended you do not edit the global configuration file /etc/lumail/lumail.lua. Instead you should copy the sample user-configuration file into place:

  $ mkdir ~/.lumail/
  $ cp user.config.lua ~/.lumail/lumail.lua

If you prefer you can name your configuration file after the hostname of the local system - this is useful if you store your dotfiles under revision control, and share them:

  $ mkdir ~/.lumail/
  $ cp user.config.lua ~/.lumail/$(hostname --fqdn).lua

The defaults in the per-user configuration file should be adequately documented, but in-brief you'll want to ensure you set at least the following:

 -- Set the location of your Maildir folders, and your sent-folder
 Config:set( "maildir.prefix", os.getenv( "HOME" ) .. "/Maildir/" );
 Config:set( "global.sent-mail", os.getenv( "HOME" ) .. "/Maildir/sent/" )

 -- Set your outgoing mail-handler, and email-address:
 Config:set( "global.mailer", "/usr/lib/sendmail -t" )
 Config:set( "global.sender", "Some User <>" )

 -- Set your preferred editor
 Config:set( "global.editor", "vim  +/^$ ++1 '+set tw=72'" )

Running from git-checkout

If you wish to run directly from a git-checkout you'll need to add some command-line flags to change the default behavior:

  • Change the location from which Lua libraries are fetched.
  • Disable the loading of the global configuration-files.

This can be achieved like so:

 $ ./lumail2 --load-path=$(pwd)/lib/ --no-default --load-file ./global.config.lua --load-file ./user.config.lua

Using Lumail

By default you'll be in the maildir-mode, and you can navigate with j/k, and select items with ENTER.

For a quick-start you can use the following bindings:

  • TAB - Toggle the display of the status-panel.
    • The panel displays brief messages when "things" happen.
    • P - Toggle the size of the panel.
    • ctrl-p enters you into a mode were you can view/scroll through past messages.
  • H - Shows the keybindings which are configured.
  • M - See your list of folders.
  • q - Always takes you out of the current mode and into the previous one.
    • Stopping at the folder-list (maildir-mode).
  • Q - Exit.

Further Notes

Further documentation can be found upon the project homepage, but there are also some notes available within this repository:


You can’t perform that action at this time.