|
1 | | -# Attachment Downloader |
| 1 | +# Gmail Attachment Downloader |
2 | 2 |
|
3 | | -The script downloads gmail atttachment(s) in no time! |
| 3 | +A Python script to easily search and download Gmail attachments based on search queries. |
4 | 4 |
|
| 5 | +## Features |
5 | 6 |
|
6 | | -# Setup Instructions |
| 7 | +- Search Gmail using Google's powerful search operators |
| 8 | +- View email search results with dates and subjects |
| 9 | +- Download attachments from search results to a specified directory |
| 10 | +- Progress tracking during downloads |
| 11 | +- User-friendly command-line interface |
7 | 12 |
|
8 | | -The script uses ezgmail module (to know more visit https://pypi.org/project/EZGmail/). To install please type the following command in your bash. |
| 13 | +## Requirements |
9 | 14 |
|
| 15 | +- Python 3.6+ |
| 16 | +- ezgmail library |
| 17 | +- Google API credentials |
| 18 | + |
| 19 | +## Setup Instructions |
| 20 | + |
| 21 | +### 1. Install Required Packages |
| 22 | + |
| 23 | +```bash |
| 24 | +pip install ezgmail |
| 25 | +``` |
| 26 | + |
| 27 | +### 2. Get Google API Credentials |
| 28 | + |
| 29 | +1. Visit the [Google API Console](https://developers.google.com/gmail/api/quickstart/python) |
| 30 | +2. Click the "Enable the Gmail API" button |
| 31 | +3. Select "Desktop app" as the OAuth Client type when prompted |
| 32 | +4. Download the `credentials.json` file and place it in the same directory as this script |
| 33 | + |
| 34 | +### 3. First-Time Authentication |
| 35 | + |
| 36 | +The first time you run the script, it will: |
| 37 | +1. Open a browser window asking you to log in to your Gmail account |
| 38 | +2. Request permission for the app to access your Gmail |
| 39 | +3. Generate a `token.json` file in the script directory to save your authentication |
| 40 | + |
| 41 | +## Usage |
| 42 | + |
| 43 | +1. Run the script: |
10 | 44 | ```bash |
11 | | -pip install EZGmail |
| 45 | +python attachment_downloader.py |
12 | 46 | ``` |
13 | 47 |
|
14 | | -Once the module is installed you will need to download credentials.json file by going to [developers.google.com](https://developers.google.com/gmail/api/quickstart/python) and clicking the Enable the Gmail API button (select "Desktop app" as OAuth Client in second step). |
| 48 | +2. Enter your search query when prompted. The script supports all Gmail search operators, for example: |
| 49 | + - `from:example@gmail.com` - Emails from a specific address |
| 50 | + - `subject:report` - Emails with "report" in the subject |
| 51 | + - `after:2023年01月01日 before:2023年12月31日` - Emails within a date range |
| 52 | + - `label:work` - Emails with a specific label |
| 53 | + - `has:pdf` - Emails with PDF attachments |
| 54 | + - Combine operators: `from:example@gmail.com subject:report has:pdf` |
| 55 | + |
| 56 | +3. Review the search results |
| 57 | + |
| 58 | +4. Confirm if you want to download the attachments |
| 59 | + |
| 60 | +5. Specify a download directory (optional) |
15 | 61 |
|
16 | | -Once you have credentials.json (in root directory of project folder), the first time you run the script it will open up a browser window asking you to log in to your Gmail account and allow "Quickstart" app to access it. A token.json file will be generated (in root directory of project folder) which your script can use to access your account. |
| 62 | +## Search Query Examples |
17 | 63 |
|
18 | | -# Outputs |
| 64 | +- `from:payroll@company.com has:spreadsheet` - Payroll spreadsheets |
| 65 | +- `subject:(invoice OR receipt) after:2023年05月01日` - Recent invoices or receipts |
| 66 | +- `from:newsletter@example.com label:newsletters` - Newsletter emails with a specific label |
| 67 | +- `filename:pdf larger:5M` - PDF attachments larger than 5MB |
| 68 | +- `from:myteam@company.com has:attachment -has:document` - Team emails with attachments that aren't documents |
19 | 69 |
|
20 | | -## Output 1 |
| 70 | +## Troubleshooting |
21 | 71 |
|
22 | | - |
| 72 | +### Authentication Issues |
23 | 73 |
|
24 | | -## Output 2 |
| 74 | +- Make sure you have the `credentials.json` file in the same directory as the script |
| 75 | +- If you change Google accounts, delete the `token.json` file and re-authenticate |
| 76 | +- If you see permission errors, check that you've enabled the Gmail API for your Google account |
25 | 77 |
|
26 | | - |
| 78 | +### Search Problems |
27 | 79 |
|
28 | | -## Output 3 |
| 80 | +- Gmail search can be case-sensitive for some operators |
| 81 | +- Ensure your search syntax is correct (see [Gmail search operators](https://support.google.com/mail/answer/7190?hl=en)) |
| 82 | +- Very large inboxes may take longer to search or time out |
29 | 83 |
|
30 | | - |
| 84 | +### Download Issues |
31 | 85 |
|
32 | | -## Output 4 |
| 86 | +- Check if you have write permissions for the download directory |
| 87 | +- Very large attachments might take time to download |
| 88 | +- Gmail API has usage limits that might affect bulk downloads |
33 | 89 |
|
34 | | - |
| 90 | +## Advanced Usage |
| 91 | + |
| 92 | +- To automate downloads, you can modify the script to accept command-line arguments |
| 93 | +- For recurring downloads, consider setting up as a scheduled task |
| 94 | +- To filter by attachment types, use search operators like `has:pdf`, `has:spreadsheet`, etc. |
| 95 | + |
| 96 | +## License |
| 97 | + |
| 98 | +This project is open source and available under the MIT License. |
35 | 99 |
|
36 | 100 | # Author |
37 | 101 |
|
38 | 102 | Contributed by Kirtan Bhatt |
| 103 | + |
| 104 | +Updated: Dennis 'dnoice' Smaltz May 19, 2025 |
0 commit comments