Overview

mailtom reads an email box and processes its contents to a text output suitable for org-mode. Each email consists in one task that will enter into your org-mode tasks.

The tool is configured with a simple configuration file. An configuration example is provided: example.cfg.

This document is the minimalist, provided as-is, documentation for mailtom version call_mailtom-version().

Install

dependencies

mailtom is known to work with python-2.7. It also needs the html2text python module.

ii  python                                              2.7.5-5                            amd64        interactive high-level object-oriented language (default version)

ii  python-html2text                                    3.200.3-2                          all          Python module for converting HTML to Markdown text

Installation process

To install mailtom locally, run:

$ python setup.py install --user

And add $HOME/.local/bin to your PATH environment variable.

Configuration file

By default, mailtom looks for a configuration file .mailtom.cfg in you $HOME directory. To provide another path to the configuration file, use the -c // --config option:

$ ./mailtom.py -c example.cfg

The command line options always take precedence over the settings of the configuration file. However, currently some configuration settings are not available via command line options!

Program output

By default, mailtom outputs the processing results to stdout.

command-line configuration

The command line -o // --output tells mailtom to append the processing results to the specified file.

file configuration

In the section global: parameter output.

Email settings

Email settings are defined in the mail section of the configuration file:

param name	default value	use
server	localhost	name of the email server
user	-	login used for connection to the email server
passwd	-	login password, in clear text
savedir	/tmp	A path directory for saving email attachments
delete_msg	False	If true, mailtom deletes the email read from the server

Email format

email subject

The email subject will constitute the header of the org-mode task. Contexts, deadlines and scheduled dates found in the email subject are removed from the subject, but the information is added to the metadata or the org-mode task.

Subject prefixes such as ‘Re: ’ or ‘Fwd: ’ are filtered out from the generated task header.

email body

The email body is copied as is in the body of the org-mode task.

email attachments

Email attachments are retrieved and copied to the attachment destination, specified in the configuration file.

Specifying contexts

A context is a word preceded by the ‘@’ character.

@phone

Dates

Date keywords

Several date formats are supported:

• date format with 8 digits, as follows: yyyymmdd
• date format with 6 digits, as follows: yymmdd
• date format with 3 or 4 digits, as follows: mmdd. In this case, the month string mm is always considered to be 2-digits long.
• date format with 1 or 2 digits, as follows: dd
• n days after the email’s date: +n or +nd [1]
• n weeks after the email’s date: +nw [1]

The date specified with the keywords mmdd and dd are computed from the today’s year, and today’s month for dd.

Specifying deadlines

A deadline is a date keyword preceded by the string “d:”.

For example, a deadline due to march the 25th, 2014:

d:140325

or within two days:

d:+2

If today is march the 22nd, 2014, d:25 will specify a deadline for the 25th of the same month, i.e. March; d:03 will also speficy a deadline for the same month, even if the deadline is already passed.

Specifying scheduled dates

A scheduled date is a date keyword preceded by the string “s:”.

For example, to schedule a task within three weeks:

s:+3w

example

The following email message:

Date: Wed, 06 Mar 2014 22:17:25 +0100
(... data filtered out)
Subject: s:+3w send a mail to Tom @work

These are my notes for this important task!

--
[Citation aléatoire]
"It would seem that you have no useful skill or talent whatsoever," he said.
"Have you thought of going into teaching?"
-+- Terry Pratchett, Mort -+-

will end into this org-mode task:

* INACTIVE  send a mail to Tom 					      :@work:
  SCHEDULED: <2014-03-27 Mar.>
  :PROPERTIES:
  :CREATED: [2014-03-06 Mar. 22:17]
  :END:
   - Note taken on [2014-03-06 Mar. 22:17] \\
These are my notes for this important task!

--
[Citation aléatoire]
"It would seem that you have no useful skill or talent whatsoever," he said.
"Have you thought of going into teaching?"
-+- Terry Pratchett, Mort -+-

development notes

pytools git-subtree

Updating the subtree:

$ git fetch pytools
$ git subtree pull --prefix mailtomlib/pytools -m '[subtree] update pytools' pytools master

legal stuff

Most of the code is written by Damien Couroussé. (Please provide patches so that can change.)

The code is covered by the GNU General Public License, version 3 or later.

Copyright (C) 2014 Damien Couroussé

This file is part of mailtom.

mailtom is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

mailtom is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with mailtom. If not, see http://www.gnu.org/licenses/.

footnotes

[1] n is an integer number