mailtidy 1.3.0

MailTidy enables the cleanup of an IMAP mail account by deleteting the accumulated dross while retaining relevant mails.

MailTidy

MailTidy enables the cleanup of an IMAP mail account by deleteting the accumulated dross while retaining relevant mails.

Much received mail, which while not spam, ceases to be revelant over time. Best practise is to delete these in a timely manner, but who does? Instead accounts become cluttered with irrelevant emails, many never read, until their volumes become too onerous to tidy manually.

Enter MailTidy, which creates a summary for each unique sender domain or each unique sender and allows an action to be performed against each summary. These actions can be filtered by age. For example, to delete mails received from the domain somewhere.com or the unique sender [e-mail] older than 365 days the DELETE action is specified with an age of 365.

Installation

MailTidy can be installed from the PyPi repository or be built and installed from source.

Installation from the PyPi Repository

Run the command pip install mailtidy. This will install the latest version of MailTidy published to the PyPi repository into your active Python environment.

Installation from Source

1. Python Poetry is used to build, install and publish MailTidy. If not already installed, follow these instructions - https://python-poetry.org/docs/#installation
2. Clone the source code from the Git repository - https://github.com/sbrewin/mailtidy.git
3. From the project's root directory execute poetry install to build and install MailTidy into your active Python environment.

Configure the IMAP account

The account details are stored in the YAML formatted file connection_data.yml located in the directory $HOME/.mailtidy. The format of the file is:

imap_server: <imap server address>
port: <imap server port>
email: <email address>
password: <imap server password>

For example:

imap_server: imap.provider.com 
port: 993
email: [e-mail]
password: mysecret

IMPORTANT: Secure the credentials stored within connection_data.yml by restricting acesss to the owner.

On *nix type systems, execute the command chmod 600 ~/.mail_tidy/connection_data.yml.

On Windows, right-click on the connection_data file and select > Properties > Security to restrict access.

Help

Help for the commands and options supported by MailTidy is available via the command line. For an oveview use the -help option, which lists the common options and the supported commands. For help with each supported command, precede -help with the name of the command.

python3 -m mailtidy -help  
python3 -m mailtidy summarise -help 
python3 -m mailtidy apply -help 

Workflow

The MailTidy workflow consists of the following steps:

1. Create summaries by executing python3 -m mailtidy summarise

   This creates a YAML formatted file containing entries for each sender in the configured IMAP account. By default summaries are created for each unique sender domain. Use the -u option to create a summary for each unique sender.

   By default, summaries are written to the file summaries.yml in the current directory. Use the -f option to specify an alternate location.

   Each summary is created with the default action of NONE and an age of 0. If applied, no changes will occur.

   By default, a summary is created per sender domain. To create a summry for each unique sender specify the -uor `--unique`` option.

2. It can take some time to summarise accounts with a large number of mails. Once done it is recommended that the produced summaries.yml file is copied to avoid the need to run a summary repeatedly while experimenting with the options.

3. Having created a copy of summaries.yml file edit the original to ammend the required Actions and Ages. Initially, you may wish to process just a subset of the senders. To do this simply leave the summaries for those you do not wish to process alone.

4. Apply the Actions by executing python3 -m mailtidy apply

   1. Actions can be restricted to a minimum and maximum number of mails recived from a sender.

      To limit an Action to senders who have received a minimum number of mails from a sender. On the command line specify -cn or --min-count with an integer > 0.

      To limit an Action to senders who have received a maximum number of mails from a sender. On the command line specify -cx or --max-count with an integer > 0.

      To limit an Action to senders who have received a number of mails from a sender within a range. On the command line specify both -cn or --min-count and -cx or --max-count. Both with an integer > 0, where the minimum must be <= to the maximum.

   2. A whitelist of domains to be excluded from processing can be passed. Use -w or --whitelist to pass the path of the whitelist file. See Whitelist below for details.

   3. Dry runs are supported and recommended prior to making destructive changes. Specify -n or --dry-run on the command line.

Summaries

A MailTidy summary contains:

• The mail address of the sender
  • This may be the full email of the sender - [e-mail] - or the domain name - somewhere.com
• A count of the number of mails received from the sender
• The UTC first date and time a mail from the sender was received
• The UTC last date and time a mail from the sender was received

Additionally, the summary contains the following fields that describe the action to be applied

• The action to be taken, default = 'none'
• The age in days below which the Action is performed, default = 0

MailTidy summaries are serialised in a YAML formatted file using the following format:

- !SenderSummary
  action: !Action 'none'
  age: 0
  count: 68
  first_datetime: 2023-03-18 19:03:03+01:00
  from_: '[e-mail]'
  last_datetime: 2023-03-18 19:03:03+01:00

The YAML file may use anchors (&) and aliases (*) to abbreviate these definitions. For example, the following defines the NONE action and then references its definition:

- !SenderSummary
  action: &id001 !Action 'none'
  age: 0
  count: 68
  first_datetime: 2023-03-18 19:03:03+01:00
  from_: '[e-mail]'
  last_datetime: 2023-03-18 19:03:03+01:00
- !SenderSummary
  action: *id001
  age: 0
  count: 1
  first_datetime: 2023-03-18 19:03:03+01:00
  from_: '[e-mail]'
  last_datetime: 2023-03-18 19:03:03+01:00

Supported Actions

MailTidy supports the following Actions, each of which is applied to mails from the sender younger than the specified age:

The below lists the supported Python Action enumeration, the action performed and their YAML equivalants...

• Action.NONE
  • No processing is applied
  • !Action 'none'
• Action.DELETE
  • Delete the selected mails
  • !Action 'delete'
• Action.ARCHIVE
  • Move the selected mails to the Archive folder
  • !Action 'archive'
• Action.PRINT_ALL
  • Print the entire content of the selected emails to stdout
  • !Action 'print_all'
• Action.PRINT_HEADERS
  • Print the headers of the selected emails to stdout
  • !Action 'print_headers'
• Action.MBOX
  • Export the selected emails to MBOX format stored in database whose location is specified by the command line option -m or --mbox-path
  • !Action 'mbox'

Whitelist

A whielist defines the domains to be excluded from apply processing. The domains are listed in a YAML formatted file:

domains:
- somewhere.com
- elsewhere.com

The path to the file is passed to the apply subcommand using -w or --whitelist:

python3 -m mailtidy apply -w whitelist.yml
python3 -m mailtidy apply -whitelist whitelist.yml 

Future Features

There are many additional features that might be added to MailTidy.

Ideas are welcome. Code contibutions particularly so 😏