{"id":31563389,"url":"https://github.com/fosterg4/gmail-cleaner-pro","last_synced_at":"2025-10-05T04:58:58.950Z","repository":{"id":309805094,"uuid":"1037614670","full_name":"FosterG4/Gmail-Cleaner-Pro","owner":"FosterG4","description":"Gmail Cleaner Pro is a simple application that helps you clean up your Gmail inbox by automatically organizing emails into categories like Promotions, Social, Forums, and Updates","archived":false,"fork":false,"pushed_at":"2025-08-13T21:38:58.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-13T23:26:05.134Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FosterG4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-13T21:08:38.000Z","updated_at":"2025-08-13T21:39:02.000Z","dependencies_parsed_at":"2025-08-13T23:26:06.777Z","dependency_job_id":"f70f4520-c7e0-419c-869a-813c4e197d99","html_url":"https://github.com/FosterG4/Gmail-Cleaner-Pro","commit_stats":null,"previous_names":["fosterg4/gmail-cleaner-pro"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/FosterG4/Gmail-Cleaner-Pro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FosterG4%2FGmail-Cleaner-Pro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FosterG4%2FGmail-Cleaner-Pro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FosterG4%2FGmail-Cleaner-Pro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FosterG4%2FGmail-Cleaner-Pro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FosterG4","download_url":"https://codeload.github.com/FosterG4/Gmail-Cleaner-Pro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FosterG4%2FGmail-Cleaner-Pro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278411254,"owners_count":25982368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-05T04:58:55.861Z","updated_at":"2025-10-05T04:58:58.939Z","avatar_url":"https://github.com/FosterG4.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gmail Cleaner Pro\n\nGmail Cleaner Pro is a simple application that helps you clean up your Gmail inbox by automatically organizing emails into categories like Promotions, Social, Forums, and Updates. It connects securely to your Gmail account using Google's official authentication system.\n\n## What This Application Does\n- **Connects to Gmail**: Uses Google's login system\n- **Organizes emails by type**: Automatically sorts Promotions, Social, Forums, and Updates\n- **Batch cleaning**: Processes multiple emails at once for efficiency\n- **Detailed logging**: Keeps track of all operations for your review\n- **Easy-to-use interface**: Simple web page to control the cleaning process\n- **API support**: Can be automated or integrated with other tools\n\n## Prerequisites (Required Before Starting)\n\n### ⚠️ IMPORTANT: Gmail API Must Be Enabled\n\n**You MUST enable the Gmail API in Google Cloud Console before this application will work.** This is a mandatory step that cannot be skipped.\n\n### What You Need:\n\n1. **Go Programming Language**\n   - Download and install Go version 1.21 or newer from [https://golang.org/dl/](https://golang.org/dl/)\n   - After installation, open a command prompt and type `go version` to verify it's installed correctly\n\n2. **Google Cloud Account** (Free)\n   - You need a Google account (the same one you use for Gmail is fine)\n   - Access to Google Cloud Console at [https://console.cloud.google.com/](https://console.cloud.google.com/)\n\n3. **Gmail API Setup** (This is the most important step)\n   - **Step 1**: Go to [Google Cloud Console](https://console.cloud.google.com/)\n   - **Step 2**: Create a new project or select an existing one\n   - **Step 3**: **ENABLE THE GMAIL API** - Search for \"Gmail API\" and click \"Enable\"\n   - **Step 4**: Create OAuth2 credentials (detailed instructions below)\n\n4. **Basic Computer Skills**\n   - Ability to open a command prompt or terminal\n   - Ability to copy and paste text\n   - Ability to edit a text file\n\n### Setting Up Google Cloud Console (Step-by-Step)\n\n**This section is crucial - follow every step carefully:**\n\n1. **Create a Google Cloud Project**\n   - Go to [Google Cloud Console](https://console.cloud.google.com/)\n   - Click \"Select a project\" at the top\n   - Click \"New Project\"\n   - Give it a name like \"Gmail Cleaner Pro\"\n   - Click \"Create\"\n\n2. **Enable the Gmail API** ⚠️ **CRITICAL STEP**\n   - In your project, go to \"APIs \u0026 Services\" → \"Library\"\n   - Search for \"Gmail API\"\n   - Click on \"Gmail API\"\n   - Click the blue \"Enable\" button\n   - Wait for it to be enabled (this may take a minute)\n\n3. **Create OAuth2 Credentials**\n   - Go to \"APIs \u0026 Services\" → \"Credentials\"\n   - Click \"Create Credentials\" → \"OAuth 2.0 Client IDs\"\n   - If prompted, configure the OAuth consent screen first:\n     - Choose \"External\" user type\n     - Fill in the required fields (App name: \"Gmail Cleaner Pro\")\n     - Add your email as a test user\n   - For Application type, choose \"Web application\"\n   - Name it \"Gmail Cleaner Pro Client\"\n   - Under \"Authorized redirect URIs\", add: `http://localhost:8080/auth/callback`\n   - Click \"Create\"\n   - **IMPORTANT**: Copy the Client ID and Client Secret - you'll need these later\n\n## How to Build the Application\n\nFollow these steps in order:\n\n### Step 1: Download the Code\n- Download or clone this project to your computer\n- Open a command prompt and navigate to the project folder\n\n### Step 2: Install Dependencies\n```bash\ngo mod tidy\n```\n*This command downloads all the required libraries*\n\n### Step 3: Build the Application\n```bash\ngo build -o bin/mailcleanerpro.exe ./cmd/server\n```\n*This creates the executable file you'll run*\n\n### Step 4: Set Up Configuration\n1. Copy the file `.env.sample` and rename it to `.env`\n2. Open the `.env` file in a text editor\n3. Replace the placeholder values with your actual Google Cloud credentials:\n   ```\n   GOOGLE_CLIENT_ID=your-actual-client-id-from-google-cloud.apps.googleusercontent.com\n   GOOGLE_CLIENT_SECRET=your-actual-client-secret-from-google-cloud\n   GOOGLE_REDIRECT_URL=http://localhost:8080/auth/callback\n   PORT=8080\n   ```\n\n## How to Run the Application\n\n### Step 1: Start the Server\n```bash\n./bin/mailcleanerpro.exe\n```\n*You should see messages indicating the server is running on port 8080*\n\n### Step 2: Use the Application\n1. Open your web browser and go to: `http://localhost:8080/`\n2. Click the \"Connect Gmail Account\" button\n3. Sign in with your Google account when prompted\n4. Grant permission for the app to access your Gmail\n5. You'll be redirected back to the application\n6. Select which email categories you want to clean\n7. Set how many emails to process per category (start with a small number like 10 for testing)\n8. Click \"Clean Now\"\n9. Review the results\n\n## Troubleshooting\n\n### Common Issues:\n\n**\"Gmail API has not been used\" Error**\n- You forgot to enable the Gmail API in Google Cloud Console\n- Go back to the Prerequisites section and follow the Gmail API setup steps\n\n**\"Invalid Client\" Error**\n- Your Client ID or Client Secret is wrong\n- Double-check your `.env` file has the correct values from Google Cloud Console\n\n**\"Redirect URI Mismatch\" Error**\n- The redirect URI in Google Cloud Console doesn't match\n- Make sure you added exactly: `http://localhost:8080/auth/callback`\n\n**Application Won't Start**\n- Make sure Go is installed correctly (`go version` should work)\n- Make sure you ran `go mod tidy` and `go build` successfully\n- Check that port 8080 isn't being used by another application\n\n## Development Mode (Optional)\n\nIf you're a developer and want to make changes to the code:\n\n```bash\n# Install Air for automatic reloading when you change code\ngo install github.com/cosmtrek/air@latest\n\n# Run in development mode (automatically restarts when you change files)\nair\n```\n\n## API Usage (For Developers)\n\nIf you want to integrate this application with other tools, you can use the API endpoints:\n\n### Authentication for API Usage\nFor API integration, you'll need to implement OAuth2 flow or use the web interface to authenticate:\n1. Use the web interface at `http://localhost:8080/` to connect your Gmail account\n2. The application handles the OAuth2 flow automatically\n3. For direct API access, implement OAuth2 client credentials flow\n\n### Clean Emails via API\n```bash\nPOST http://localhost:8080/api/clean\nContent-Type: application/json\nX-Access-Token: \u003cyour-access-token\u003e\n\n{\n  \"categories\": [\"CATEGORY_PROMOTIONS\", \"CATEGORY_SOCIAL\"],\n  \"max_per_category\": 100,\n  \"action\": \"trash\"\n}\n```\n\n### Check Status\n```bash\nGET http://localhost:8080/api/status\nX-Access-Token: \u003cyour-access-token\u003e\n```\n\n**Note:** For API usage, you can obtain the access token by authenticating through the web interface first, then extracting it from the browser's local storage or implementing your own OAuth2 flow.\n\n**⚠️ Security Note:** Never commit your `.env` file to version control. The `.env.sample` file is provided as a template with example values only.\n\n## Project Structure\n\n```\nmailcleanerpro/\n├── cmd/server/          # Main application\n├── internal/            # Internal application code\n├── pkg/                 # Reusable packages\n├── web/                 # Web interface files\n├── bin/                 # Built executable (created after build)\n├── .env                 # Your configuration file (you create this)\n└── README.md            # This documentation\n```\n\n## Security \u0026 Privacy\n\n- **Your data stays private**: The application only accesses your Gmail through Google's secure API\n- **No data storage**: Email content is never stored on your computer\n- **Secure authentication**: Uses Google's OAuth2 system (the same login system Gmail uses)\n- **Audit trail**: All operations are logged so you can see exactly what happened\n- **Minimal permissions**: Only requests the minimum access needed to clean emails\n\n## What's Coming Next\n\n- **Better filtering**: More options for which emails to clean\n- **Scheduled cleaning**: Set it to run automatically\n- **Preview before delete**: See what will be deleted before it happens\n\n## Support\n\nIf you have problems:\n1. Check the Troubleshooting section above\n2. Make sure you followed all the Prerequisites steps\n3. Verify your Google Cloud Console setup is correct\n4. Check that the Gmail API is enabled\n\nFor additional help, please open an issue on the project repository.\n\n## License\n\nThis project is open source and available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffosterg4%2Fgmail-cleaner-pro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffosterg4%2Fgmail-cleaner-pro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffosterg4%2Fgmail-cleaner-pro/lists"}