Gmail Attachment Downloader

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.

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 "[e-mail]" \
  --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 "[e-mail]" \
  --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