Getting Started

Petr Baudis edited this page Aug 11, 2013 · 2 revisions


  • A Gmail or Google Apps mail account (or see below)
  • Python 2.5 or later


Get the latest code from GitHub:

git clone

You will also need Cheetah (a template system) installed. You can download it and then follow the installation instructions. If you are using an apt-based Linux distribution sudo apt-get install python-cheetah may be enough for you.


Go into the mail-trends directory:

cd mail-trends

Run the program, replacing the username and passwords as appropriate (if you omit the password in the commandline you will be (securely) prompted for it):

python \ \
  --use_ssl \ \, \

You will be prompted for the password for your account (you can also use --password= to specify it as an argument. The --me argument lets you specify what emails should be considered as being sent to/from you.

The output is in HTML, placed in out/index.html. Open that in your favorite web browser.

Other options

--skip_labels does not categorize messages into labels (there are not stats that use them yet).

--filter_out=... can be used to ignore certain messages. You can use, or to filter out by recipient, sender or list (you can have multiple filter clauses by separating them with commas).

You can pass in --record and --replay as command line arguments to respectively capture and play black message fetches from the IMAP server. This is meant to aid in development by speeding up data fetches.

--max_messages=NNNN can be used to limit the number of messages that are fetched. Normally the most recent messages are selected, use --random_subset to specify that the messages be chosen over all the messages.

Personal IMAP server

If you are using your personal IMAP server, adjust the commandline options appropriately and edit the variables MAILBOX_GMAIL_ALL_MAIL and MAILBOX_GMAIL_PREFIX appropriately (e.g. INBOX and . or sent and /, depends on your folder setup).


Running on more than about 25k messages may hit a recursion limit in - try reducing the number of messages.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.