Lumail - The console email client

This project is now archived, and "complete". See #361 for more details.

Technical FAQ


How can I see all message headers?

By default when viewing a message only a small set of headers are displayed, but you can press "G" to toggle between viewing some or all of them. (This is configured in the default keymap.lua file.)


How can I read a HTML message?

By default lumail will present the text/plain view of a message if available. It will do this even for messages which contain both text/plain and text/html parts.

To view all available MIME-parts you may press "A" to move into attachment-mode. From there you can highlight any part and press "return", or "space" to view them as text.

If you wish to use a browser you can press "l" to open the currently-highlighted text/html part in (l)ynx, or w to view in (w)3m.


How does GPG support work?

Signing, or encrypting outgoing messages is pretty simple, and only involves piping the message through the mimegpg binary, which will handle the GPG operation.

For validating and decrypting incoming messages things are more complex, and involves the use of a Lua filter-function message_replace().

The message_replace function will be invoked with the path to the message on-disk, and will either return "" or an updated path. If an updated path is returned then that will be treated as the incoming-message-path - allowing transformations to be made.

mimegpg has options to both decrypt and validate a message passed through it, so we use those options to replace the body of each incoming message with a decrypted/validated copy of itself - which has the net result that the process is seamless.

Further details are explained in the GPG documentation in the repository.


How can I apply a function to all messages?

To get access to all the messages you can use the get_messages() function, this will return all messages which are currently available (respecting the value of index.limit variable).

Once you have the list you can then iterate as you would in Lua:

local msgs = get_messages()

for index,object in ipairs(msgs) do
    -- Do something with object here...

That said there is a simpler way, via the functional-programming module which is included you can invoke a method on every message in one step. The following example marks all messages as being read:

function mark_all_read()
   local msgs = get_messages()
   if ( msgs and #msgs > 0 ) then
      Fun.object_map( 'mark_read', msgs )
      Panel:append( "There are no messages" )

Similarly this method will delete all currently visible messages:

function delete_all()
   local msgs = get_messages()
   if ( msgs and #msgs > 0 ) then Message.delete, msgs )
      Panel:append( "There are no messages" )

Please see lib/functional.lua for details of the difference between and Fun.object_map.


How can I improve the speed of lumail?

Opening large lists of messages can be slow, to improve that there is a caching system which will cache the formatted version of messages.

It is expected that the first time you open a large folder the cache will be built, and after that things will be snappy and fast.

The cache is automatically written to disk when you exit lumail via "Q", or as a background action every two minutes.


Parsing of headers is broken (to/from/subject)?

We use GMime for parsing headers, message-bodies, and attachments.

By default GMime is pretty strict, but it has a looser mode which can be enabled via custom flags. If you're seeing some oddities with decoding of headers in particular please set the environmental variable RFC2047 to a non-empty value.

Upon a typical host you could do that via:

RFC2047=1 lumail [...args...]


The output looks wrong with foreign character sets.

The intention is that all output will be sent to your terminal/console in UTF-8.

So the first step is to explicitly setup a locale, if you've not already done so:

$ export LC_ALL=en_US.UTF8

Once you've configured a suitable locale you can test it via this simple Perl script:

$ perl -Mcharnames=:full -CS -wle 'print "\N{EURO SIGN}"'

If that outputs the correct Euro symbol ("€") then your terminal is configured correctly, and all Lumail output should be correct. If not please report a bug.


Is there an easter-egg?

That would be a shocking waste of programmer resources!

Don't press ctrl-l to see the results of that squandered time!