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 "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:

bash

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