gmail-statement-fetcher

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.

# Option A: .env file in the project directory (recommended)
# Create {baseDir}/.env with:
#   GMAIL_USER=[e-mail]
#   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:

# In .env:
#   SINOPAC_PDF_PASSWORD=xxx
#   CTBC_ZIP_PASSWORD=xxx

Commands

Fetch statements (IMAP mode, default)

python3 {baseDir}/fetcher.py

Dry run — preview matches without downloading

python3 {baseDir}/fetcher.py --dry-run --verbose

Custom config and output directory

python3 {baseDir}/fetcher.py --config "{{config_path}}" --output-dir "{{output_dir}}"

OAuth mode

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)