Package: pygmailsorter
Sort your emails automaticallyThepygmailsorteris a python module to automate the filtering of emails on the Google mail service using the their API. It assigns
labels to emails based on their similarity to other emails assigned to the same label.MotivationMany people struggle with the increasing email volume leading to hundreds of unread emails. As the capabilities of even the best search engine are limited when it comes to large numbers of emails, the only way to keep an overview is filing emails into folders. The manual work of filing emails into folders is tedious, still most people are too lazy to create email filters and keep their email filters up to date. Finally, in the age of mobile computing when most people access their emails from their smartphone, the challenge of sorting emails is more relevant than ever.The solution to this challenge is to automatically filter emails depending on their similarity to existing emails in a given folder. This solution was already proposed in a couple of research papers ranging from the filtering of spam emails1to the specific case of sorting emails into folders2. Even a couple of open source prototypes were available like3and4.This is basically a similar approach specific to the Google Mail API. It is a python script, which can be executed periodically for example with a cron task to sort the emails for the user.InstallationThepygmailsorteris available on the conda-forge or pypi repositories and can be installed using either:conda install -c conda-forge pygmailsorteror alternatively:pip install pygmailsorterConfigurationThepygmailsorterrequires two steps of configuration:The user has to create a Google Mail API credentials filecredentials.jsonfollowing theGoogle Mail API documentation.Access to an SQL database, this can be provided asconnection string, alternativelypygmailsorteris going to use
a local SQLite database namedemail.dblocated in the current directory. This results in the followingconnection string:sqlite:///email.dbPython interfaceImport theGmailclass and the functionload_client_secrets_filefrom thepygmailsortermodulefrom pygmailsorter import Gmail, load_client_secrets_fileInitialize pygmailsorterCreate agmailobject from theGmail()class:gmail = Gmail(
    client_config=load_client_secrets_file(
        client_secrets_file="/absolute/path/to/credentials.json"
    ),
    connection_str="sqlite:////absolute/path/to/email.db",
)Based on the configuration from the previous section, the functionload_client_secrets_fileis used to load thecredentials.jsonfile and provide its content as python dictionary to theclient_configparameter of theGmail()class. In addition to theclient_configparameter theGmail()class also requires a connection to an SQL database
which is provided asconnection_str. In addition theemail_download_formatcan be specified as eithermetadataorfull, where the primary difference is whether the content of the email is stored or not. Finally, as optional
parameter theportcan be specified which is used to authenticate the Google Mail API via a web browser, by default
this8080.Sync local database with email accountTo reduce the communication overhead, the emails are stored locally in an SQLite database.gmail.update_database(quick=False)By setting the optional flagquicktoTrueonly new emails are downloaded while changes to existing emails are
ignored.Generate pandas dataframe for emailsLoad all emails from the local SQLite database and combine them in a pandas DataFrame for further postprocessing:df = gmail.get_all_emails_in_database()Download specific label from email serverDownload emails with the label"MyLabel"from the email server:df = gmail.download_emails_for_label(label="MyLabel")In this case the emails are not stored in the local SQLite database.Filter emails using machine learningAssign new email labels to the emails with the label"MyLabel":gmail.filter_messages_from_server
    label="MyLabel",
    recommendation_ratio=0.9,
)This functionality is based on thedownload_emails_for_label()function above. It checks the server for new emails for
a selected label"MyLabel". Then reloads the machine learning model from the local SQLite database and trys to predict
the correct labels for these emails. Therecommendation_ratiodefines the level of certainty required to actually move
the email, with0.9equalling a certainty of 90%.Command Line interfaceThe command line interface implements the same functionality as the Python interface, it supports the following options:pygmailsorter -c/--credentialspath to credentials file provided by Google e.g.credentials.json.pygmailsorter -d/--databaseconnection string to connect to database e.g.sqlite:///email.db.pygmailsorter -u/--updateupdate the local email database and retrain the machine learning model.pygmailsorter -l/--label=MyLabelassign new labels to the emails with labelMyLabel.pygmailsorter -p/--portport for authentication webserver to run e.g.8080.