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.
• Gemini AI Subject Summarization (--ai): Summarizes email content into concise subjects using Google Gemini models, optimized for low token consumption.
• Model Selection & Persistence: List available models (--ai_models) and save your preferred model in configuration (--ai_model MODEL).
• 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

Use Gemini AI to summarize the email content into a concise subject:

eml_rename --ai --save

AI Configuration (Optional)

To use the AI subject generation feature (--ai), a Google Gemini API Key is required.

1. Set API Key

Option A: Environment Variable

export GOOGLE_API_KEY='your_api_key_here'

Option B: Configuration File

Create a file in ~/.config/eml-rename/config.ini:

[auth]
GOOGLE_API_KEY = your_api_key_here

[ai]
model_name = gemini-2.5-flash
delay = 2

2. Manage AI Models

• List available models:

  eml_rename --ai_models
  

• Change and save your preferred model:

  eml_rename --ai_model gemini-2.5-flash
  

  (This automatically saves the model to your config.ini so you don't need to specify it every time).

• Automatic Fallback: If a configured model becomes unavailable or deprecated, eml_rename warns you and falls back automatically to gemini-2.5-flash.

Command-Line Options