eml_rename project

Script that renames .eml email files in a directory or by specific path using email metadata (Date, From, Subject).

Idea

I needed this tool to classify and order my email files at work. I took this idea from an article by Armand Niculescu (August 20, 2014) at https://www.media-division.com/using-python-to-batch-rename-email-files/ , so thanks and I hope you like this code.

Installation

pip install eml_rename 

Features

• Automatic Metadata Renaming: Extracts date, time, sender, and subject to generate filenames in the format: YYYYMMDD HHMM [From] Subject.eml.
• Target Single File, Directory, or Current Working Directory: By default processes all *.eml files in the current working directory, or you can pass an optional path to a specific file or directory.
• Directory Preservation: Renamed files stay in their original folder, even when targeting files in subdirectories or absolute paths.
• Safe Simulation by Default: Previews changes without renaming unless --save is specified.
• Protects Manual Edits: If a file already has the YYYYMMDD HHMM [From] format, the script won't overwrite manual edits to the subject unless --force is used.
• Ollama AI Subject Summarization (--ai MODEL): Summarizes email content into concise subjects using local Ollama models (e.g., llama3, mistral, etc.).
• Configurable Ollama Server (--ai_url): Connect to your Ollama instance (defaults to http://localhost:11434).
• Concurrent Processing: Uses multi-threading to process large archives fast.

Usage & Examples

1. Simulation (Default)

Run in the current directory to preview changes without modifying files:

eml_rename

2. Rename All Emails in Current Directory

Use --save to apply the renames:

eml_rename --save

3. Rename a Specific File or Directory

Pass a path to a single .eml file or a directory:

# Specific file
eml_rename path/to/email.eml --save

# Specific directory
eml_rename /path/to/archive/ --save

4. Force Overwriting Already Renamed Files

eml_rename --force --save

5. Custom Maximum Length

Set a custom length for generated filenames (default is 140 characters):

eml_rename --length 160 --save

6. AI-Powered Subject Summarization (Ollama)

Use Ollama AI to summarize the email content into a concise subject by specifying the model:

eml_rename --ai llama3 --save

AI Configuration (Optional)

AI-powered subject generation is completely optional and powered locally or remotely by Ollama.

1. Requirements & Setup

1. Install Ollama from ollama.com or via your system's package manager.
2. Start the Ollama daemon:

   ollama serve
   

3. Download a fast, lightweight model suitable for concise summaries:

   # Recommended lightweight models:
   ollama pull gemma4:e2b
   ollama pull qwen3.5:2b
   ollama pull llama3.2:3b
   

2. Usage

Pass the desired model name to --ai:

eml_rename --ai gemma4:e2b --save

Tip: If files already have the prefix YYYYMMDD HHMM [from] from a previous run, use --force to re-summarize them with AI:

eml_rename --ai gemma4:e2b --force --save

3. Configuring Ollama Server URL

By default, eml_rename connects to http://localhost:11434. If Ollama is running on another port, machine, or container, configure the URL using one of the following methods (in order of priority):

Option A: Command-Line Argument

eml_rename --ai gemma4:e2b --ai_url http://192.168.1.50:11434 --save

Option B: Environment Variable

export OLLAMA_HOST='http://192.168.1.50:11434'

Option C: Configuration File

Create or edit ~/.config/eml-rename/config.ini:

[ai]
url = http://192.168.1.50:11434

Command-Line Options