Gmail Attachment Downloader

这是一款无需谷歌云API的Gmail附件下载工具，基于IMAP协议实现。支持批量下载，可按发件人、主题、日期范围、文件扩展名等条件筛选附件，还提供预览模式查看匹配结果。典型场景包括导出发票、账单、收据等文件至本地文件夹。需输入邮箱地址、应用密码，可选筛选条件及保存路径，执行后返回下载统计报告，遇问题会给出排查建议。

whauff

热度 37.91

最近更新 2026-05-11 17:43:03

分类：自动化依赖：代码执行 / 读写文件应用场景：自动化脚本 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add gmail-attachment-downloader

Metadata

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

Confirm the user has Gmail IMAP enabled and an app password.
Decide the destination folder and filters.
Run scripts/download_gmail_attachments.py with explicit arguments.
Report: downloaded count, skipped count, and destination folder. If --summary-json is used, prefer reading that file for the final report.
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