gmailLabelStorage

A simple Python tool to analyze Gmail storage usage by label. This utility uses IMAP to calculate the storage space used by emails associated with specific labels or all labels in your Gmail account.

Features

• 📊 Analyze storage usage for a specific Gmail label
• 📈 Get storage breakdown for all labels at once
• 🔍 List all available labels in your account
• 📏 Display results in bytes, MB, and GB
• 🔒 Simple IMAP authentication with app-specific passwords
• ⚡ Fast - uses batch operations and lightweight RFC822.SIZE
• 🎯 No external dependencies - uses Python's built-in imaplib

Prerequisites

• Python 3.7 or higher
• Gmail account with IMAP enabled
• App-specific password (if using 2-Step Verification)

Installation

1. Clone this repository:

git clone https://github.com/YOUR_USERNAME/gmailLabelStorage.git
cd gmailLabelStorage

2. No dependencies to install! Uses Python's built-in libraries.

3. Set up credentials:

   • Create a .env file in the project directory with:

     GMAIL_EMAIL=your.email@gmail.com
     GMAIL_PASSWORD=your-app-specific-password
     

   • Or set environment variables GMAIL_EMAIL and GMAIL_PASSWORD

4. Generate an app-specific password:

   • Go to Google Account App Passwords
   • Select "Mail" and your device
   • Copy the generated password

5. Enable IMAP in Gmail:

   • Gmail Settings → Forwarding and POP/IMAP
   • Enable IMAP access

Usage

List all available labels

python gmailLabelStorage.py --list-labels

Analyze storage for a specific label

python gmailLabelStorage.py --label "Important"

Analyze storage for all labels

python gmailLabelStorage.py

Example Output

Single Label Analysis

============================================================
Storage Analysis for Label: Work
============================================================
Message Count: 1,234
Total Size (Bytes): 524,288,000
Total Size (MB): 500.00
Total Size (GB): 0.4883
============================================================

All Labels Analysis

================================================================================
Storage Analysis for All Labels
================================================================================
Label                          Messages      Size (MB)       Size (GB)
--------------------------------------------------------------------------------
INBOX                             5,432        2,500.50          2.4419
Work                              1,234          500.00          0.4883
Personal                            892          300.25          0.2932
...
--------------------------------------------------------------------------------
TOTAL                             7,558        3,300.75          3.2234
================================================================================

Authentication

On first run, the script will:

1. Open your default web browser
2. Ask you to sign in to your Google account
3. Request permission to read your Gmail data
4. Save credentials locally in token.json for future use

Security Notes

• The script only requests read-only access to your Gmail account
• Credentials are stored locally in token.json
• Never share your credentials.json or token.json files
• Add both files to .gitignore (already included)

Rate Limits

The Gmail API has rate limits. For accounts with many messages, the script may take some time to complete. Progress indicators are shown during processing.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made
• NonCommercial — You may not use the material for commercial purposes

See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

"credentials.json not found" error

Make sure you've downloaded your OAuth credentials from Google Cloud Console and saved them as credentials.json in the project directory.

Authentication fails

Try deleting token.json and re-authenticating.

Slow performance

The Gmail API has rate limits. For large mailboxes, consider analyzing specific labels instead of all labels at once.

How It Works

The tool uses IMAP's RFC822.SIZE attribute to calculate email sizes:

1. Connects to Gmail via IMAP
2. Selects the specified label/folder
3. Fetches RFC822.SIZE for all messages in batches
4. Aggregates sizes and displays results

Disclaimer

This tool provides storage based on RFC822.SIZE from IMAP. Values represent the size of the raw email message (including headers, body, and attachments). Actual storage usage in Gmail may vary slightly due to Gmail's internal storage optimizations.