gmail-statement-fetcher

Category: Testing & Security | Uploader: notoriouslab | Downloads: 0 | Version: v1.0（Latest）

Automatically download bank/financial statement PDFs from Gmail via IMAP or OAuth. Config-driven bank rules, UID dedup, ZIP extraction, PDF decryption.

Changelog: Source: GitHub https://github.com/notoriouslab/gmail-statement-fetcher

Directory Structure

Current level: tree/main/

📁 tests/
- 📄 __init__.py 0 B
- 📄 test_fetcher.py 17.8 KB
📄 .env.example 1.6 KB
📄 .gitignore 336 B
📄 config.example.json 2.9 KB
📄 CONTRIBUTING.md 1.7 KB
📄 fetcher.py 35.7 KB
📄 LICENSE 1.0 KB
📄 README.en.md 9.0 KB
📄 README.md 9.0 KB
📄 requirements.txt 1.0 KB
📄 SECURITY.md 2.4 KB
📄 SKILL.md 3.6 KB

SKILL.md

---
name: gmail-statement-fetcher
description: Automatically download bank/financial statement PDFs from Gmail via IMAP or OAuth. Config-driven bank rules, UID dedup, ZIP extraction, PDF decryption.
metadata: {"openclaw":{"emoji":"📬","version":"1.0.2","homepage":"https://github.com/notoriouslab/gmail-statement-fetcher","requires":{"bins":["python3"],"env_via_dotenv":["GMAIL_USER","GMAIL_APP_PASSWORD"]}}}
---

# gmail-statement-fetcher

Automatically download bank/financial statement PDFs from Gmail.

## When to use

- User asks to download bank statements from Gmail
- User wants to set up automated statement fetching
- User asks to fetch encrypted/password-protected PDF statements
- User wants to extract PDFs from ZIP attachments in email

## Credential setup

Credentials MUST be loaded from environment or secrets file — **NEVER inline passwords in shell commands**.

```bash
# Option A: .env file in the project directory (recommended)
# Create {baseDir}/.env with:
#   GMAIL_USER=user@gmail.com
#   GMAIL_APP_PASSWORD=your-app-password
# The fetcher loads .env automatically via python-dotenv.

# Option B: export from secrets file
export GMAIL_USER=$(python3 -c "import json; print(json.load(open('$HOME/.paiop_secrets.json'))['gmail_user'])")
export GMAIL_APP_PASSWORD=$(python3 -c "import json; print(json.load(open('$HOME/.paiop_secrets.json'))['gmail_app_password'])")
```

Bank PDF/ZIP passwords follow the same pattern — use env vars or .env, never inline:
```bash
# In .env:
#   SINOPAC_PDF_PASSWORD=xxx
#   CTBC_ZIP_PASSWORD=xxx
```

## Commands

### Fetch statements (IMAP mode, default)
```bash
python3 {baseDir}/fetcher.py
```

### Dry run — preview matches without downloading
```bash
python3 {baseDir}/fetcher.py --dry-run --verbose
```

### Custom config and output directory
```bash
python3 {baseDir}/fetcher.py --config "{{config_path}}" --output-dir "{{output_dir}}"
```

### OAuth mode
```bash
AUTH_METHOD=oauth python3 {baseDir}/fetcher.py
```

## Options

| Flag | Description |
|---|---|
| `--config` | Path to config JSON (default: `<script dir>/config.json`) |
| `--output-dir` | Directory to save PDFs (default: `<script dir>/downloads`) |
| `--state-file` | Path to UID dedup store (default: `<output-dir>/.processed_uids.json`) |
| `--auth` | `imap` or `oauth` (overrides `AUTH_METHOD` env var) |
| `--dry-run` | Preview matched emails without downloading |
| `--verbose` | Enable debug logging |

## Environment variables

| Variable | Mode | Description |
|---|---|---|
| `GMAIL_USER` | IMAP | Gmail address |
| `GMAIL_APP_PASSWORD` | IMAP | Gmail App Password |
| `AUTH_METHOD` | Both | `imap` (default) or `oauth` |
| `OAUTH_CREDENTIALS` | OAuth | Path to `credentials.json` from GCP Console |
| `OAUTH_TOKEN` | OAuth | Path to `token.json` (auto-generated) |
| `{BANKID}_PDF_PASSWORD` | Both | PDF decryption password for a specific bank (e.g. `SINOPAC_PDF_PASSWORD`). Takes precedence over `pdf_password` in config.json. |
| `{BANKID}_ZIP_PASSWORD` | Both | ZIP extraction password for a specific bank (e.g. `CTBC_ZIP_PASSWORD`). Takes precedence over `zip_password` in config.json. |

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Completed successfully |
| 1 | Runtime error (IMAP/OAuth failure, config missing) |

## Notes

- IMAP mode uses Python stdlib only — no pip install needed
- Bank matching rules are config-driven — add banks via `config.json`, no code changes
- UID dedup prevents re-downloading already-processed emails across runs
- Supports password-protected PDFs (via pikepdf) and ZIP attachments
- ZIP extraction includes streaming bomb guard (100 MB cap)
- `.processed_uids.json` stores hashed subjects only (no PII)

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

gmail-statement-fetcher

Directory Structure

SKILL.md

Report

Notice