Gmail Attachment Downloader

---

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.

python3 scripts/download_gmail_attachments.py \
  --gmail-user "$GMAIL_USER" \
  --gmail-pass "$GMAIL_PASS" \
  --sender "auth@shove.xforceplus.com" \
  --subject "发票" \
  --since "01-Jan-2025" \
  --extensions ".pdf,.ofd" \
  --save-folder "~/Documents/walmart-invoices" \
  --max-results 200

Preview matches without writing files:

python3 scripts/download_gmail_attachments.py \
  --gmail-user "$GMAIL_USER" \
  --gmail-pass "$GMAIL_PASS" \
  --sender "auth@shove.xforceplus.com" \
  --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

Script entry point: scripts/download_gmail_attachments.py