{"id":30668321,"url":"https://github.com/dnouri/gmailctrl","last_synced_at":"2025-08-31T23:47:48.429Z","repository":{"id":299138178,"uuid":"1002173610","full_name":"dnouri/gmailctrl","owner":"dnouri","description":"A TUI to manage bulk email in Gmail","archived":false,"fork":false,"pushed_at":"2025-06-24T22:45:36.000Z","size":125,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-24T23:32:45.871Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnouri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-14T21:52:51.000Z","updated_at":"2025-06-24T22:45:40.000Z","dependencies_parsed_at":"2025-06-14T22:40:30.611Z","dependency_job_id":"39663d4c-e932-421d-9dcf-57cf2c1f3e8c","html_url":"https://github.com/dnouri/gmailctrl","commit_stats":null,"previous_names":["dnouri/gmailctrl"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dnouri/gmailctrl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fgmailctrl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fgmailctrl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fgmailctrl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fgmailctrl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnouri","download_url":"https://codeload.github.com/dnouri/gmailctrl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fgmailctrl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273056119,"owners_count":25037875,"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-08-31T02:00:09.071Z","response_time":79,"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-08-31T23:47:33.555Z","updated_at":"2025-08-31T23:47:48.413Z","avatar_url":"https://github.com/dnouri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gmailctrl\n\nA TUI to manage bulk email in Gmail.\n\n![gmailctrl screenshot](https://raw.githubusercontent.com/dnouri/gmailctrl/main/docs/screenshot.png)\n\n## Motivation\n\nIs your Gmail inbox overflowing? Between newsletters, notifications, and promotional content, it's easy to lose track of what's important. On top of that, finding and downloading attachments scattered across hundreds of emails can be a tedious, manual process.\n\n`gmailctrl` is a fast, keyboard-driven terminal application designed to help you take back control of your Gmail account. It offers two powerful features to tackle digital clutter:\n\n1.  **Efficient Graymail Management:** It groups emails by sender, letting you archive or delete large volumes of messages with a few keystrokes, making inbox cleanup fast and efficient.\n2.  **Bulk Attachment Downloader:** It allows you to easily download all attachments from a specified period (e.g., the last 30 days). Files are automatically organized into folders by sender and named with the email date, creating a clean, local archive of your important documents.\n\nWhether you're clearing out old subscriptions or gathering financial documents for your records, `gmailctrl` streamlines the process, saving you time and frustration.\n\nThis project, including its source code and this documentation, was written entirely using AI.\n\n## Key Dependencies\n\n*   [Textual](https://github.com/Textualize/textual) for the terminal user interface.\n*   [Google API Client Library for Python](https://github.com/googleapis/google-api-python-client) for interacting with the Gmail API.\n\n## Installation\n\nTo install `gmailctrl`, you will need Python 3.10+ and `uv`.\n\n1.  Create and activate a virtual environment:\n    ```sh\n    uv venv\n    source .venv/bin/activate\n    ```\n\n2.  Install the application directly from GitHub:\n    ```sh\n    uv pip install git+https://github.com/dnouri/gmailctrl\n    ```\n\n## Setup and First Run\n\nBefore you can use `gmailctrl`, you need to provide it with API credentials to access your Gmail account.\n\n### 1. Get `credentials.json`\n\nThe application uses OAuth 2.0 to securely access your data. You'll need to get a credentials file from the Google Cloud Console.\n\n1.  Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2.  Create a new project (or select an existing one).\n3.  Enable the **Gmail API** for your project. You can find it in the \"APIs \u0026 Services\" \u003e \"Library\" section.\n4.  Go to \"APIs \u0026 Services\" \u003e \"Credentials\".\n5.  Click **Create Credentials** and select **OAuth client ID**.\n6.  Choose **Desktop app** as the application type.\n7.  After creation, click the **Download JSON** button for the client ID you just created.\n8.  Save this file as `credentials.json` in the directory where you will run `gmailctrl`.\n\n### 2. First Launch\n\nWhen you run `gmailctrl` for the first time, it will automatically open a new tab in your web browser.\n\n1.  You will be asked to log in to your Google account.\n2.  You will then be prompted to grant `gmailctrl` permission to \"Read, compose, send, and permanently delete all your email from Gmail\". This is required for the application to read, archive, and delete emails on your behalf.\n3.  After you approve, a `token.json` file will be created in the same directory. This file securely stores your authorization and will be used for future sessions, so you won't have to log in every time.\n\n## Usage\n\nAfter authenticating, you will be presented with a main menu.\n\n### Email Management\n\nSelecting \"Manage Emails\" starts the email management workflow. After an initial scan, you will be presented with the main screen, which lists all email groups found in your inbox, sorted by the number of messages from each sender.\n\n#### Main View \u0026 Keybindings\n\n| Key         | Action                                                 |\n|-------------|--------------------------------------------------------|\n| `Space`     | Toggle selection for the highlighted sender group.     |\n| `a`         | Archive all emails from all selected sender groups.    |\n| `d`         | Delete (move to trash) all emails from selected groups.|\n| `Enter`     | Open the detail view for the highlighted sender group. |\n| `Ctrl+R`    | Manually refresh the entire email list.                |\n| `q`         | Quit the application.                                  |\n\nActions like archiving and deleting will always ask for confirmation.\n\n#### Detail View\n\nPressing `Enter` on a sender group opens the detail view. This screen shows a summary for that specific group and provides `Archive` and `Delete` buttons to act on all emails from only that sender. After the action is complete, you will be returned to the main list, which will be refreshed.\n\n### Attachment Downloader\n\nSelecting \"Download Attachments\" from the main menu allows you to download all attachments from your inbox over a specified period.\n\n1.  You will be prompted to enter the number of days to look back.\n2.  The application will then find all attachments from that period and download them.\n3.  Files are saved to a `downloads/` directory in the folder where you run `gmailctrl`.\n4.  Inside `downloads/`, subdirectories are created for each sender's email address (e.g., `downloads/some.sender@example.com/`).\n5.  Downloaded files are named using the format `YYYY-MM-DD - originalfilename.pdf` to ensure they are sorted chronologically.\n6.  If a file with the exact same name and date already exists, a numeric suffix is added to prevent overwrites (e.g., `2025-03-03 - report-1.pdf`).\n7.  The creation/modification time of each downloaded file is also set to match the date of the email it was attached to.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fgmailctrl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnouri%2Fgmailctrl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fgmailctrl/lists"}