# 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.

- Skill: `lord1egypt/gmail-attachment-downloader` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/gmail-attachment-downloader`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/gmail-attachment-downloader/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/gmail-attachment-downloader

---


# 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](references/setup.md)
- Script entry point: [scripts/download_gmail_attachments.py](scripts/download_gmail_attachments.py)