Contents: System requirements, Installation, Usage, Organization and Tips
Most recently tested with: python 3.6 (April 2019).
System requirements
I have only tested bomail on some Linux flavors. It will definitely not work on Windows (filenames contain UUIDs which will be a problem), although porting would be doable in principle. Likely works on Mac, never tried.
If you want to play with it, I suggest you back up your email first.
bomail is written in python 3 and requires it to run. It assumes new emails are fetched from your email provider and deposited in Maildir format using some mail retrieval agent such as getmail (this will be covered below).
Installation
I'll use a Debian-based system (e.g. Ubuntu, Mint) as an example, and I've only tested this on a couple distributions, but adapt the commands to your package manager and hopefully it'll work out.
Install prerequisites and bomail
(1) Install python3, pip3 (a package manager for python), and bomail (pip3 should automatically install the datetime and python-dateutil packages):
$ sudo apt install python3 python3-pip
$ python3 -m pip install --upgrade pip --user
$ python3 -m pip install bomail --user
(April 2019: pip seems to push us into the --user option above, which only installs things for your username and not everyone on the system. You may also have to tell your computer where to find the program, by running
(2) Install and configure a mail retrieval agent such as getmail. This is a program that fetches your email and stores it on your computer. bomail expects new mail to arrive in ~/mail/new/ and bomail moves these emails to ~/mail/cur/ once it processes them. But both of these locations can be configured to something else. Main example: walkthrough for installing and configuring getmail.
(3) Run bomail from the command line:
$ bomail
If the configuration file ~/.config/bomail.conf does not exist, the program runs a very quick setup. It asks for a few basics (name, email address) and creates ~/.config/bomail.conf, also creating the data directory (~/bomail by default) if it does not exist. The next time you run it, bomail will launch normally (run it with no arguments for help, or see below).
Configuration
(4) Check out the configuration file (above). To send mail, you need to fill in details of the SMTP server to connect to and your email and password. You will have to look up the SMTP details for your provider, i.e. the hostname and port. If using getmail, you can leave the password commented out and bomail will try to read the password from the file ~/.getmail/getmailrc, if it has permissions.
You should also make sure the location of new mail is correct (by default, ~/mail/new/). You might like to glance down the list of other options too for things like what text editor to use to write email.
(5) The other thing to definitely edit (at some point) is bomail/metadata/mail_handlers.txt. This file controls options for handling new emails. For example, it controls automatically tagging emails that match given search queries, such as being from a certain sender. This file's location is printed when running bomail with no arguments.
Usage
You can run bomail with no arguments to get some help and list the possible commands.
The main one is bomail gui which launches the interface (which I call the "GUI" even though that's kind of exactly wrong).
In the "gui", actions make direct calls to the command-line programs, so you can get more info by running those commands with "-h" (for "help") to see how to use it.
Note that on the command line, most of them read a list of filenames from stdin to act on.
So a common usage pattern is for example bomail search "chocolate" | bomail chstate -c to "close" all emails with chocolate in them.
Get new mail ("g" key)
This runs bomail process and bomail check_sched.
process looks in ~/mail/new/ (or wherever you've configured) for new emails.
If it finds any, it unpacks their attachments, converts the email to bomail's mailfile format, and checks ~/bomail/metadata/mail_handlers.txt for any actions like auto-tagging.
check_sched checks whether any "scheduled" emails have passed their scheduled time, and if so, it "opens" them.
Change state of mail ("ocst" keys)
The "o" key, for open, is equivalent to piping the file list to bomail chstate -o and changes their state to open. The "c" key changes their state to closed and "t" trashes the files.
The "s" key is for changing the state to scheduled.
bomail then requests a schedule string, for example, p3H schedules it for "plus 3 hours" from now, while 2030-01-01 schedules it for New Year's day 2030.
This is equivalent to bomail chstate -s p3H and so on.
See bomail chstate -h and bomail help datestr for more.
Search mail (create/edit tabs) ("+e" keys)
Pressing "+" asks for a query string and creates a new tab with that query; "e" edits the current tab to a given query string.
This is equivalent to running bomail search query and displaying results in the tab (grouped into threads if threading is turned on).
See bomail search -h for info on search queries.
Compose new or edit existing draft ("w" key)
This gives a variety of options depending on if the cursor is currently on an email, draft or on nothing. If on an email, you can reply, reply-all, forward, or just write a blank new draft unrelated to the current email. If on a draft, you can edit various aspects, add/remove attachments, etc. See also bomail compose -h.
When editing files, it opens the mailfile (that is, the raw text file format bomail uses) in the program defined in ~/.bomailrc as edit_program. The default is vim. Above the ============ line are metadata "headers" used by bomail. You can edit the from, to, cc, bcc, and subject lines; the others probably shouldn't be edited by hand. The body of the email goes below the ========== line.
Add/delete tags ("ad" keys)
Pretty self-explanatory except I tried to make a fancy interface since I use it so often and wanted to encourage myself to tag things a lot. You can use TAB to try to autocomplete at least up to the next "/". See also bomail mailfile -h, which is also the command-line way to get information about emails (like author, subject, etc), and bomail help tags for info on "dirlike" tags.
Send email ("S" key)
I made this hotkey capitalized to reduce chances of a mis-type, since it can't be undone (though there's a confirmation stage after pressing S). Connects to your smtp server using configuration in ~/.bomailrc and sends the email, including adding any attachments you've specified by their path. See bomail send -h.
Organization and Tips
When importing an email, bomail creates a "mailfile" and stores it in ~/bomail/email under its date. This has a plain-text version of the email and some metadata. Attachments are extracted into a corresponding folder in ~/bomail/attachments. (The interface displays a little plus-sign after the author if an email has an attachment.) The original email file is moved to (by default) ~/mail/cur/ under its date, so you can access it if bomail was unable to properly convert the text of the email, for instance.
When you quit the "gui", bomail prints out a list of filenames currently under the cursor, in case you want to know or use them.
When scheduling or searching, you can use either absolute dates like 2050-03-25 or 2050-03, or relative dates like p3d (plus 3 days from now) or m4w (minus four weeks before now). See bomail help datestr for more info.
For initially importing a large dataset of emails: First make sure there aren't any duplicate message ids, then put them in ~/mail/new/, then I recommend running bomail process from the command line instead of the gui (but it probably doesn't matter).
I've only seen one case where two non-identical emails had the same message id (it was a talk announcement and a re-sending of the talk announcement some time later).
However, the same email downloaded from different sources may not be byte-for-byte identical (for example, sometimes the line break encodings are different).
Importing took around 5-6min when I did it on ~6GB of email, with most of that time taken by pthon opening and parsing the emails.