Skill: whauff/gmail-attachment-downloader (version 1.1.0)

--- name: gmail-attachment-downloader description: | Download Gmail attachments through IMAP when the user wants to pull invoices, statements, or other files from Gmail into a local folder. Use it when the task involves Gmail attachment export, sender/subject/date filtering, or batch downloading attachments without setting up Google Cloud APIs. metadata: author: "whauff" version: "1.1.0" --- # Gmail Attachment Downloader Use this skill when the user wants files downloaded from Gmail to the local machine. ## When To Use Trigger this skill when the user asks to: - Download Gmail attachments in bulk - Export invoices, statements, or receipts from Gmail - Filter Gmail attachments by sender, subject, date range, extension, or limit - Save Gmail attachments into a local folder without using Google Cloud APIs Do not use this skill for: - Sending email - Modifying or deleting mailbox contents - Managing Google OAuth projects ## Inputs To Collect Collect or infer these inputs before running the script: - `gmail_user`: Gmail address - `gmail_pass`: Gmail app password - `sender`: optional sender filter - `subject`: optional subject filter - `since`: optional start date in `DD-Mon-YYYY` - `before`: optional end date in `DD-Mon-YYYY` - `extensions`: optional comma-separated extension list such as `.pdf,.ofd` - `save_folder`: destination folder on the local machine - `max_results`: optional safety limit for matched messages - `dry_run`: optional preview mode when the user wants to inspect matches first If the user did not specify `save_folder`, choose a clear folder under their home directory and state it explicitly before running. ## Execution Run the bundled script with explicit arguments instead of editing source files. ```bash python3 scripts/download_gmail_attachments.py \ --gmail-user "$GMAIL_USER" \ --gmail-pass "$GMAIL_PASS" \ --sender "[REDACTED_SECRET]" \ --subject "发票" \ --since "01-Jan-2025" \ --extensions ".pdf,.ofd" \ --save-folder "~/Documents/walmart-invoices" \ --max-results 200 ``` Preview matches without writing files: ```bash python3 scripts/download_gmail_attachments.py \ --gmail-user "$GMAIL_USER" \ --gmail-pass "$GMAIL_PASS" \ --sender "[REDACTED_SECRET]" \ --extensions ".pdf,.ofd" \ --save-folder "~/Documents/walmart-invoices" \ --dry-run ``` Environment variables are also supported: - `GMAIL_USER` - `GMAIL_PASS` ## Workflow 1. Confirm the user has Gmail IMAP enabled and an app password. 2. Decide the destination folder and filters. 3. Run `scripts/download_gmail_attachments.py` with explicit arguments. 4. Report: downloaded count, skipped count, and destination folder. If `--summary-json` is used, prefer reading that file for the final report. 5. If authentication fails, tell the user to re-check IMAP and the app password. ## Failure Handling - If `GMAIL_USER` or `GMAIL_PASS` is missing, stop and ask for it. - If mailbox auto-detection cannot find Gmail All Mail, fall back to `INBOX`. - If no messages match, suggest loosening sender/subject/date filters. - If downloads are zero, suggest removing extension filtering. ## Resources - Setup details: [references/setup.md](references/setup.md) - Script entry point: [scripts/download_gmail_attachments.py](scripts/download_gmail_attachments.py)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)