EIML

Extended-IMAP Message Labeler (EIML) simplifies programmatic organization of emails on servers that support Gmail's label extensions. The task of analyzing and generating labels is farmed out to a user-specified Python module or shell script while EIML handles applying the changes.

This is not an official Google product.

Synopsis

EIML is a script used for organizing emails on Gmail IMAP servers. It downloads unprocessed messages, feeds them to a labeler and then applies the returned labels to the emails. The labeler can be a Python function or any program that can read data from stdin and write to stdout. EIML works with Python 2.7 and Python 3.2+.

Setup and Configuration

Before running EIML for the first time, please read this section in its entirety.

Create Labeler

A labeler can be a function defined within a Python script or an arbitrary subprocess. The raw email passed into Python function will be a "str" in Python 2 and "bytes" in Python 3. In the "examples" folder are two message labeling scripts that should be useful as a starting point. One script is written in pure Bash, and the other script is written in Python, but they both process messages in a similar way.

Python scripts report label assignments by yielding strings whereas subprocesses report them printing them one per line. If text returned by the labeler starts with a "+" or "-", the text will be interpreted as an IMAP flag addition or deletion, respectively instead of a label assignment. IMAP flags control special properties of messages like whether or not the message is marked as read; a script that returned "+Seen" as part of its output would cause a message to be marked "Read." For more information on the flags, refer to section 2.3.2 of RFC 3501. Once a message is processed, it is not moved to the Inbox by default. A message must explicitly be moved to the Inbox by the labeler returning the string "Inbox". When no labels are assigned to a message, the message is ignored in future polling cycles until EIML is restarted, so it is strongly recommended that labelers always return at least one label lest the script's memory usage grow indefinitely.

Once a script has been created, it can be tested using the "--dry-run" flag and the "--source-label"; the "--source-label" flag should be set to whatever label contains the messages to be used for the dry-run. In most cases, the desired dry-run invocation should look like this if an incoming mail filter specifically for EIML has not yet been setup:

eiml.py ... --dry-run --source-label=Inbox LABELER

This will run make EIML simulate applying labels to every message in the Inbox.

Launching

The basic usage for EIML is eiml.py [OPTION...] LABELER. Once the labeler is written, the way EIML is launched depends on how the script should be executed. When the labeler is a Python script, LABELER is given in the form of $PATH_TO_PYTHON_SCRIPT:$FUNCTION_NAME. For example, if EIML were executed using the example Python script, the invocation would look like this:

eiml.py ... examples/python-labeler.py:labeler

If the last argument passed to EIML does not appear to be a Python script and function, it will be interpreted as a shell script and launched using $SHELL -c "$LABELER", so launching EIML with the Bash script could look like either of the following two command assuming the Bash script has the executable bit set:

eiml.py ... ./examples/bash-labeler.sh
eiml.py ... "bash -c ./examples/bash-labeler.sh"

When a username is not specified or a password file is not specified, EIML will prompt for either piece of the login credentials as needed. To learn about EIML's other features, review the sections below.

Incoming Message Filter

In order for EIML to work properly, a label needs to be applied to all incoming messages that the script should process. By default, EIML will query messages labeled "Unprocessed", but this can be changed with the "--source-label" option. Create a filter for things with the following properties:

• Doesn't include chats
• Matches all messages with a size greater than 0 bytes

Messages that match the criteria should:

• Skip the Inbox (Archive them)
• Have the label "Unprocessed" (or whatever the is used for "--source-label") applied to them

If EIML should not process all messages, adjust the search criteria as desired. Alternatively, the gmail-filter.xml file in this repository can be imported into Gmail. For instructions on creating and importing filters, please read the Gmail help page Using filters.

Tying it Together

Once EIML is configured as desired, create a shell script to launch it with the necessary parameters. EIML will exit with a status of 2 if there is an error that likely cannot be resolved without human intervention such as incorrect login information or invalid command-line flags, and it will exit with a status of 1 for all other errors.

Since an exit status of 1 often indicates a temporary network or server-side issue, it may be a good idea to automatically relaunch EIML after a delay if it terminates with an exit status of 1 for improved resilience, e.g.:

#!/bin/sh
while true; do
    ./eiml.py ...
    exit_status="$?"
    if [ "$exit_status" -ne 1 ]; then
        exit "$exit_status"
    else
        sleep 60
    fi
done

Options

--auto-archive-delay=NUMBER

When specified, all messages in the Inbox that have been marked read for at least this amount of seconds will be archived at the end of each message processing cycle. When no labeler is specified, this option must be set.

--dry-run

When set, labels returned by the labeler will not applied to messages, and the "--auto-archive" flag is ignored.

-h, --help

Show script documentation and exit.

--host=HOST

Address of the IMAP host. Host must support Gmail IMAP extensions. Defaults to "imap.gmail.com".

--ignore-if-read

When specified, unprocessed messages that have already been read will be ignored.

--password-file=FILE

File containing the password needed to log into the IMAP account.

--polling-period=NUMBER

Number of seconds to wait between polling for and processing messages marked with label defined with "--source-label". Defaults to 5 seconds.

--source-label=LABEL

Label that contains messages that need to be processed by the script. Defaults to "Unprocessed".

--username=EMAIL

Email address of the account to access.

-q

Decrease logging verbosity. Can be used repeatedly to further decrease verbosity.

-v

Increase logging verbosity. Can be used repeatedly to further increase verbosity.