# Gmail Email Archiver
A Python tool to archive all emails from your Gmail inbox using the Gmail API. Emails are moved from the inbox to the archive (All Mail), keeping them accessible while decluttering your inbox.
## Features
- **Safe archiving**: Emails are moved to archive, not deleted
- **Batch processing**: Process emails in configurable batches for efficiency
- **Dry run mode**: Preview what would be archived without making changes
- **Progress tracking**: Real-time feedback during the archiving process
- **OAuth authentication**: Secure Google OAuth 2.0 authentication
- **Status checking**: Check inbox count without making changes
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install archive-all-my-mails
```
### Option 2: Install from source
1. Clone this repository:
```bash
git clone <repository-url>
cd archive-all-my-mails
```
2. Install dependencies using uv (recommended) or pip:
```bash
# Using uv (recommended)
uv sync
# Or using pip
pip install -e .
```
## Gmail API OAuth Setup
Before using the archiver, you need to set up OAuth credentials with Google.
### Step 1: Create a Google Cloud Project
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Click "Select a project" at the top of the page
3. Click "New Project"
4. Enter a project name (e.g., "gmail-archiver")
5. Click "Create"
### Step 2: Enable the Gmail API
1. In your project, go to "APIs & Services" > "Library"
2. Search for "Gmail API"
3. Click on "Gmail API" from the results
4. Click "Enable"
### Step 3: Create OAuth 2.0 Credentials
1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth client ID"
3. If prompted, configure the OAuth consent screen:
- Choose "External" user type
- Fill in the required application information
- Add your email to test users
4. For application type, select "Desktop application"
5. Give it a name (e.g., "Gmail Archiver")
6. Click "Create"
### Step 4: Get Your Credentials
1. After creating the OAuth client, you'll see your credentials:
- **Client ID** (looks like: `xxxxx.apps.googleusercontent.com`)
- **Client Secret** (a random string)
2. Copy these values - you'll need to provide them when running the script
3. Keep these credentials secure and do not share them
## Usage
### Basic Commands
```bash
# Check inbox status (dry run to see what would be archived)
archive-gmail --dry-run
# Archive all emails with confirmation prompt
archive-gmail
# Archive all emails without confirmation
archive-gmail --yes
# Provide credentials as command line arguments
archive-gmail --client-id "your-client-id" --client-secret "your-secret"
# Process in smaller batches (default is 100)
archive-gmail --batch-size 50
```
### First Run Authentication
When you first run the script:
1. You'll be prompted to enter your Client ID and Client Secret
2. A browser window will open automatically
3. Sign in to your Google account
4. Grant permission to access your Gmail
5. The script will save authentication tokens locally (`token.pickle`) for future use
### Command Line Options
- `--dry-run`: Preview what would be archived without making changes
- `--client-id`: Google OAuth Client ID
- `--client-secret`: Google OAuth Client Secret
- `--batch-size`: Number of emails to process in each batch (default: 100)
- `--yes`: Skip confirmation prompt
## How It Works
1. **Authentication**: Uses OAuth 2.0 to securely connect to your Gmail account
2. **Email Discovery**: Fetches all emails from your inbox
3. **Batch Processing**: Processes emails in configurable batches for efficiency
4. **Archiving**: Removes the "INBOX" label from emails, moving them to archive
5. **Reporting**: Provides feedback on success/failure counts
## Safety Features
- **No email deletion**: Emails are archived, not deleted
- **Dry run mode**: Test the process without making changes
- **Confirmation prompts**: Asks for confirmation before archiving (unless `--yes` flag is used)
- **Batch processing**: Handles large inboxes efficiently
- **Error handling**: Graceful handling of API errors and rate limits
## Security Notes
- Your Client ID and Client Secret are sensitive - keep them secure
- The script creates a `token.pickle` file to store authentication tokens
- Never share your credentials or commit them to version control
- The script only requests the minimum required Gmail permissions
## Troubleshooting
### Common Issues
**"Invalid credentials"**
- Double-check your Client ID and Client Secret
- Ensure you're using the correct credentials from Google Cloud Console
**"Access denied"**
- Make sure you've enabled the Gmail API in Google Cloud Console
- Verify OAuth consent screen is properly configured
- Check that your email is added as a test user
**"Browser doesn't open for authentication"**
- Try deleting `token.pickle` and re-authenticating
- Ensure you have a default browser configured
- Check firewall settings that might block the redirect
**"Rate limit exceeded"**
- The script handles rate limits automatically with exponential backoff
- If issues persist, try reducing the batch size with `--batch-size`
### Getting Help
If you encounter issues:
1. Try running with `--dry-run` first to test authentication
2. Check the error messages for specific guidance
3. Verify your Google Cloud Console setup matches the instructions above
4. Delete `token.pickle` and re-authenticate if authentication seems stuck
## License
This project is provided as-is for personal use. Please review and comply with Google's API Terms of Service when using this tool.
Raw data
{
"_id": null,
"home_page": null,
"name": "archive-all-my-mails",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "archive, email, gmail, google-api, productivity",
"author": "Nathan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e9/c3/6a0c621919e82688caa52c07d4f8819d8b3b91b1f151dd7b55c2783af45e/archive_all_my_mails-0.1.0.tar.gz",
"platform": null,
"description": "# Gmail Email Archiver\n\nA Python tool to archive all emails from your Gmail inbox using the Gmail API. Emails are moved from the inbox to the archive (All Mail), keeping them accessible while decluttering your inbox.\n\n## Features\n\n- **Safe archiving**: Emails are moved to archive, not deleted\n- **Batch processing**: Process emails in configurable batches for efficiency\n- **Dry run mode**: Preview what would be archived without making changes\n- **Progress tracking**: Real-time feedback during the archiving process\n- **OAuth authentication**: Secure Google OAuth 2.0 authentication\n- **Status checking**: Check inbox count without making changes\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install archive-all-my-mails\n```\n\n### Option 2: Install from source\n\n1. Clone this repository:\n\n ```bash\n git clone <repository-url>\n cd archive-all-my-mails\n ```\n\n2. Install dependencies using uv (recommended) or pip:\n\n ```bash\n # Using uv (recommended)\n uv sync\n\n # Or using pip\n pip install -e .\n ```\n\n## Gmail API OAuth Setup\n\nBefore using the archiver, you need to set up OAuth credentials with Google.\n\n### Step 1: Create a Google Cloud Project\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/)\n2. Click \"Select a project\" at the top of the page\n3. Click \"New Project\"\n4. Enter a project name (e.g., \"gmail-archiver\")\n5. Click \"Create\"\n\n### Step 2: Enable the Gmail API\n\n1. In your project, go to \"APIs & Services\" > \"Library\"\n2. Search for \"Gmail API\"\n3. Click on \"Gmail API\" from the results\n4. Click \"Enable\"\n\n### Step 3: Create OAuth 2.0 Credentials\n\n1. Go to \"APIs & Services\" > \"Credentials\"\n2. Click \"Create Credentials\" > \"OAuth client ID\"\n3. If prompted, configure the OAuth consent screen:\n - Choose \"External\" user type\n - Fill in the required application information\n - Add your email to test users\n4. For application type, select \"Desktop application\"\n5. Give it a name (e.g., \"Gmail Archiver\")\n6. Click \"Create\"\n\n### Step 4: Get Your Credentials\n\n1. After creating the OAuth client, you'll see your credentials:\n - **Client ID** (looks like: `xxxxx.apps.googleusercontent.com`)\n - **Client Secret** (a random string)\n2. Copy these values - you'll need to provide them when running the script\n3. Keep these credentials secure and do not share them\n\n## Usage\n\n### Basic Commands\n\n```bash\n# Check inbox status (dry run to see what would be archived)\narchive-gmail --dry-run\n\n# Archive all emails with confirmation prompt\narchive-gmail\n\n# Archive all emails without confirmation\narchive-gmail --yes\n\n# Provide credentials as command line arguments\narchive-gmail --client-id \"your-client-id\" --client-secret \"your-secret\"\n\n# Process in smaller batches (default is 100)\narchive-gmail --batch-size 50\n```\n\n### First Run Authentication\n\nWhen you first run the script:\n\n1. You'll be prompted to enter your Client ID and Client Secret\n2. A browser window will open automatically\n3. Sign in to your Google account\n4. Grant permission to access your Gmail\n5. The script will save authentication tokens locally (`token.pickle`) for future use\n\n### Command Line Options\n\n- `--dry-run`: Preview what would be archived without making changes\n- `--client-id`: Google OAuth Client ID\n- `--client-secret`: Google OAuth Client Secret\n- `--batch-size`: Number of emails to process in each batch (default: 100)\n- `--yes`: Skip confirmation prompt\n\n## How It Works\n\n1. **Authentication**: Uses OAuth 2.0 to securely connect to your Gmail account\n2. **Email Discovery**: Fetches all emails from your inbox\n3. **Batch Processing**: Processes emails in configurable batches for efficiency\n4. **Archiving**: Removes the \"INBOX\" label from emails, moving them to archive\n5. **Reporting**: Provides feedback on success/failure counts\n\n## Safety Features\n\n- **No email deletion**: Emails are archived, not deleted\n- **Dry run mode**: Test the process without making changes\n- **Confirmation prompts**: Asks for confirmation before archiving (unless `--yes` flag is used)\n- **Batch processing**: Handles large inboxes efficiently\n- **Error handling**: Graceful handling of API errors and rate limits\n\n## Security Notes\n\n- Your Client ID and Client Secret are sensitive - keep them secure\n- The script creates a `token.pickle` file to store authentication tokens\n- Never share your credentials or commit them to version control\n- The script only requests the minimum required Gmail permissions\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Invalid credentials\"**\n\n- Double-check your Client ID and Client Secret\n- Ensure you're using the correct credentials from Google Cloud Console\n\n**\"Access denied\"**\n\n- Make sure you've enabled the Gmail API in Google Cloud Console\n- Verify OAuth consent screen is properly configured\n- Check that your email is added as a test user\n\n**\"Browser doesn't open for authentication\"**\n\n- Try deleting `token.pickle` and re-authenticating\n- Ensure you have a default browser configured\n- Check firewall settings that might block the redirect\n\n**\"Rate limit exceeded\"**\n\n- The script handles rate limits automatically with exponential backoff\n- If issues persist, try reducing the batch size with `--batch-size`\n\n### Getting Help\n\nIf you encounter issues:\n\n1. Try running with `--dry-run` first to test authentication\n2. Check the error messages for specific guidance\n3. Verify your Google Cloud Console setup matches the instructions above\n4. Delete `token.pickle` and re-authenticate if authentication seems stuck\n\n## License\n\nThis project is provided as-is for personal use. Please review and comply with Google's API Terms of Service when using this tool.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python tool to archive all emails from Gmail inbox using the Gmail API",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/nathanael/archive-all-my-mails",
"Issues": "https://github.com/nathanael/archive-all-my-mails/issues",
"Repository": "https://github.com/nathanael/archive-all-my-mails"
},
"split_keywords": [
"archive",
" email",
" gmail",
" google-api",
" productivity"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a659401c5d44e53ffb4decf3bb8b06f80401f83217f1105e16f9a712a74318fb",
"md5": "f9b3bcebe8d7bedd2cabfaf8880759e0",
"sha256": "8fae3744f678c368c3d4ca859afa101abffadebbb7d7bcf6424bcfbf7a414291"
},
"downloads": -1,
"filename": "archive_all_my_mails-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9b3bcebe8d7bedd2cabfaf8880759e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10359,
"upload_time": "2025-07-27T09:29:13",
"upload_time_iso_8601": "2025-07-27T09:29:13.701344Z",
"url": "https://files.pythonhosted.org/packages/a6/59/401c5d44e53ffb4decf3bb8b06f80401f83217f1105e16f9a712a74318fb/archive_all_my_mails-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e9c36a0c621919e82688caa52c07d4f8819d8b3b91b1f151dd7b55c2783af45e",
"md5": "b2879cbf664d44e86533a4c0bd789bd6",
"sha256": "70ead0f8832fb333bb1f5f93659dd0d571eaf8a51057209c4f8ef97e39b83837"
},
"downloads": -1,
"filename": "archive_all_my_mails-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b2879cbf664d44e86533a4c0bd789bd6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 34274,
"upload_time": "2025-07-27T09:29:14",
"upload_time_iso_8601": "2025-07-27T09:29:14.735154Z",
"url": "https://files.pythonhosted.org/packages/e9/c3/6a0c621919e82688caa52c07d4f8819d8b3b91b1f151dd7b55c2783af45e/archive_all_my_mails-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 09:29:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nathanael",
"github_project": "archive-all-my-mails",
"github_not_found": true,
"lcname": "archive-all-my-mails"
}
JSON
